# Prowler Documentation > ## Agent Instructions > Prowler product naming: Prowler App is now Prowler Local Server, and Prowler Enterprise is now Prowler Private Cloud. Always use the current names when answering. The full product reference is at /getting-started/products: Open Source projects are Prowler CLI, Prowler Local Server, Prowler Local Dashboard, and Prowler SDK; Prowler Products are Prowler Cloud, Prowler Private Cloud, Prowler Hub, Prowler Lighthouse AI, and Prowler MCP. # Changelog Source: https://docs.prowler.com/changelog New features and improvements in each Prowler release **v5.48.0** November 6, 2026 ### ⚡ Prowler Realtime — Detection and Remediation for AWS > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). A scan tells you what was wrong at the time it ran. **Prowler Realtime** watches an AWS account's CloudTrail as events happen, checks each risky call with a targeted Prowler check on the resource it touched, and responds the way the account's policy says, minutes after the change instead of at the next scan. * Events arrive from an EventBridge to SQS feed, deployed with the CloudFormation or Terraform templates, or from a CloudTrail `LookupEvents` fallback. * Each account has a policy mode: `monitor` alerts, `pr` proposes the change as a Terraform pull request behind a security gate, and `auto` fixes the resource through an optional remediation-only role, with every action recorded and reversible. Auto-fix can run as a dry run first. * The `/realtime` dashboard has an overview with posture, open violations and verified fixes, plus Detections, Remediation with revert, a live Event stream, Prioritized findings and opt-in Cost anomalies. Details open in the side panel next to Lighthouse AI, and one Configuration page covers the event feed, enforced frameworks, remediation access, alerts and activation. * Accounts show labelled demo data until Realtime is set up, and the status can be shared as a redacted statement to copy or download. * A new **Manage Realtime** role permission controls who can change the policy; reading stays open to roles that can see the provider. Lighthouse AI and the MCP Server get Realtime tools to manage the policy and feed, read detections and actions, and revert them. ### 🎯 Issues — Everything From the Side Panel > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). * The issue side panel now holds everything the full issue page had, and the page is gone: **Findings** and **Resources** tabs, the evidence lines of each leg, the compliance frameworks under the title and **Send to Jira** in the header menu. A finding clicked in the attack path or the Findings tab opens inside the panel, with a breadcrumb back. * A **Contextual Fix** Lighthouse AI skill on the issue panel reads the open legs and the findings of the path, leads with the single change that closes it fastest and then lists per-resource fixes grouped by check. * Issues with dozens of findings load their attack path, findings and resources again; the panel used to send every finding UID from the browser and larger issues were rejected. ### 🚀 First Scan — Findings and Sample Data While You Wait * Scans run checks from the highest to the lowest severity, so critical and high findings are stored first. While a tenant's first scan is running, the Findings page shows its findings as they arrive with a progress banner, and executing scans get a **View Early Findings** action. * Finding groups show the check title instead of the check ID during a tenant's first scan. * **Prowler Cloud:** until the first scan completes, Overview, Findings, Resources, Compliance, Issues and Attack Paths show labelled sample data from a demo AWS account, with a banner that follows the real scan and swaps the sample out when it finishes. ### 🤖 AWS — Bedrock AgentCore Coverage A new `bedrockagentcore` service collects AgentCore gateways, gateway targets, agent runtimes, memories, browsers, code interpreters and token vaults, with three new checks in the service and one in CloudTrail: * `bedrockagentcore_full_access_policy_attached` flags IAM roles with the AgentCore full access managed policies, and `bedrockagentcore_payments_process_payment_role_separation` flags roles allowed both `CreatePaymentSession` and `ProcessPayment`. Contributed by @tamg-aws. Thank you! * `cloudtrail_agentcore_data_events_enabled` verifies that actively logging trails record AgentCore data events for every AgentCore resource type in use. Contributed by @tamg-aws. Thank you! * `bedrockagentcore_runtime_vpc_configured` verifies that AgentCore runtimes use VPC network mode. Contributed by @Nithin078. Thank you! ### ☁️ Cloudflare, GitHub and Vercel Checks * **Cloudflare:** new `account` service with `account_two_factor_enforced`, `account_member_two_factor_enabled`, `account_super_admins_limited`, `account_api_token_expiration_set`, `account_api_token_ip_restriction_enabled` and `account_api_token_recently_used`; new `r2` service with `r2_bucket_public_dev_url_disabled`, `r2_bucket_cors_no_wildcard_origin` and `r2_bucket_custom_domain_min_tls_secure`; new `workers` service with `workers_script_observability_enabled`, `workers_script_workers_dev_disabled`, `workers_script_preview_urls_disabled` and `workers_script_no_secrets_in_plain_text_bindings`; and `zone_firewall_no_skip_all_traffic_rules`, which flags enabled skip rules that match all traffic and bypass the managed WAF or rate limiting. * **GitHub:** `repository_secret_scanning_push_protection_enabled` flags repositories that accept pushes containing secrets. * **Vercel:** `project_environment_no_secrets_with_public_prefix` flags secret-like environment variables that frontend frameworks inline into the browser bundle through prefixes such as `NEXT_PUBLIC_` or `VITE_`, and `project_linked_to_git_repository` flags projects that can only receive unreviewed CLI deployments. Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### 📋 Compliance * GDPR for Azure, mapping Articles 25, 30 and 32 to existing Azure checks. Contributed by @m-khan-97. Thank you! * Cloudflare mappings for NCSC Cyber Essentials 3.3. Contributed by @ethanhawkes-gif. Thank you! * The NATO D32 compliance icon uses the official NATO/OTAN logo. ### 🏢 Prowler Private Cloud on AWS Marketplace Prowler Private Cloud is listed on AWS Marketplace as Pay as You Go and 10 and 25 account bundles, installed in the customer's own AWS account and billed on the AWS bill. Marketplace installations report scanned accounts hourly, send a monthly usage statement and show a sidebar notice when the subscription is ending or paused; Lighthouse AI uses OpenAI gpt-oss-120b on Amazon Bedrock with the installation's own role. See [Prowler Private Cloud](/getting-started/products/prowler-private-cloud-aws-marketplace) for plans and installation. ### 🛠️ Improvements and Fixes * The OSS CLI HTML report, `prowler dashboard` and its terminal output show a short note on bringing findings to Prowler Cloud. Nothing is uploaded, and `PROWLER_NO_PROMOTIONS=1` turns the dashboard note off; Prowler Cloud and Private Cloud reports never include it. * WAFv2 `ListWebACLs` is paginated, so accounts with more than one page of Web ACLs are fully scanned, and CloudFront Web ACL rules, logging and tags are read even when the scan excludes `us-east-1`. Contributed by @tamg-aws. Thank you! * CloudTrail trail status and event selectors are read per trail, so one unreadable trail no longer leaves the others unread. * `vpc_endpoint_connections_trust_boundaries` skips VPC endpoints whose service does not support endpoint policies, such as Amazon SES SMTP, instead of failing them. Contributed by @jvgiorgi12. Thank you! * `guardduty_ai_protection_enabled` and `iam_user_access_not_stale_to_sagemaker` join the `gen-ai` category. * `zone_challenge_passage_configured` reports Cloudflare zones without a challenge passage TTL as non-compliant. * MongoDB Atlas connection errors include the HTTP status, error code and detail Atlas returns instead of a generic HTTP error. * Findings partitions tile exactly, so findings no longer land in the default partition at each window boundary and miss the age-out. Contributed by @AlexeyShalaev. Thank you! * The cross-provider compliance view shows the per-provider breakdown for frameworks without a dedicated UI mapper. * The Overview cards fit every screen width and no longer stack into a single column on narrower screens. * **Prowler Cloud:** Lighthouse AI settings accept a Bedrock API key as an alternative to AWS access keys. ### 🔐 Security Updates * `POST /api/v1/tokens/github` and `POST /api/v1/tokens/google` only accept an OAuth authorization code and reject caller-supplied `access_token` and `id_token` values, which could have been issued to another OAuth client. Reported by @Mrcyberwarri0r. Thank you! * GCP `service_account` credentials must be of type `service_account` with a Google `token_uri`, in the SDK and in provider secrets, rejecting `external_account` configurations and custom token endpoints that could read local files or reach internal URLs. Reported by @Mrcyberwarri0r. * Python base image upgraded to 3.12.16 in the SDK and API images and 3.13.18 in the MCP Server image, patching CVE-2026-115557. * PowerShell upgraded to 7.5.13 in the SDK and API images, bundling .NET runtime 9.0.22, and `apt` to 3.0.4. * `oauthlib` upgraded to 4.0.1 in the SDK and API images, patching the OAuth device flow bearer token disclosure. * `pyasn1` upgraded to 0.6.5 in the SDK and the API and `joserfc` to 1.7.5 in the SDK and the MCP Server, patching the ASN.1 decoding and JWE decryption denial of service advisories. * `h2` upgraded to 4.4.1 and `werkzeug` to 3.1.9 in the SDK and the API, patching the duplicate Host header request smuggling and the Windows device name bypass in `safe_join`. * `fastmcp` upgraded to 3.4.10 in the MCP Server, patching the skipped authorization check on direct calls to transformed components. * `zod`, `js-yaml`, `vitest` and transitive UI dependencies upgraded to patched versions, resolving 33 npm audit advisories. ### 🙌 External Contributors Thank you to our community contributors for this release! * @tamg-aws: AWS Bedrock AgentCore inventory, IAM role separation and CloudTrail data event checks, and the WAFv2 pagination and CloudFront fixes ([#12557](https://github.com/prowler-cloud/prowler/pull/12557), [#12558](https://github.com/prowler-cloud/prowler/pull/12558), [#12563](https://github.com/prowler-cloud/prowler/pull/12563), [#12658](https://github.com/prowler-cloud/prowler/pull/12658)) * @Nithin078: AWS `bedrockagentcore_runtime_vpc_configured` check ([#12800](https://github.com/prowler-cloud/prowler/pull/12800)) * @m-khan-97: GDPR compliance framework for Azure ([#11590](https://github.com/prowler-cloud/prowler/pull/11590)) * @ethanhawkes-gif: Cyber Essentials 3.3 mappings for Cloudflare ([#12641](https://github.com/prowler-cloud/prowler/pull/12641)) * @jvgiorgi12: VPC endpoint policy support fix ([#13169](https://github.com/prowler-cloud/prowler/pull/13169)) * @AlexeyShalaev: findings partition bounds fix ([#12766](https://github.com/prowler-cloud/prowler/pull/12766)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.48.0) for the complete list of changes. **v5.47.0** October 29, 2026 ### 🧭 Add Provider — One Step to Connect Any Provider The add-provider wizard follows the same model for every provider: one connect step, then the launch step. Adding an Azure subscription used to take six screens; now the account, its alias and its credentials are one form, and a single submit registers the account, stores the secret and tests the connection. * A failed connection test shows inline, keeps the values and turns the action into **Retry connection** without registering the account twice. * Access methods show as cards on the same step for AWS, GCP, Microsoft 365, GitHub, Alibaba Cloud and Cloudflare, and AWS, Azure and GCP switch to their organization flow through tabs. * Users with the Manage Account permission can invite a teammate to finish the connection for every provider, not only AWS. * **Ask Lighthouse AI** opens beside the wizard without closing it. It guides the connection from the Prowler docs by default and, when asked, connects the provider itself after confirming the provider, UID and credential field names, never echoing a secret back. * Product tours and the guided onboarding sequence are removed; new tenants still land on the add-provider wizard. ### 🎯 Issues — Verdicts Explained in the List > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). * The issue list leads with the verdict, shows the attack path under each title and adds a **Why** column with the five evidence legs, so the reason for a verdict reads without opening the issue. The summary tiles become one line with the folded findings and the findings already covered by a control. * A row opens in the side panel, next to Lighthouse AI, with the verdict, legs, remediation, triage and an **Attack path** tab with the issue graph, instead of expanding the issue inline. * The menu entry is renamed to **Exploitability issues**. ### ☁️ Azure and AWS Checks * `network_application_gateway_waf_enabled` and `network_application_gateway_http2_enabled` cover Azure Application Gateways and their WAF policies, mapped to CIS 5.0 and 6.0. Contributed by @BabafemiB. Thank you! * `iam_subscription_owners_between_2_and_3` verifies that each Azure subscription has between two and three Owners, counting owners inherited from management groups, mapped to CIS 5.0 and 6.0. Contributed by @BabafemiB. Thank you! * The AWS security group internet exposure checks treat CIDRs in one ingress rule that together cover `0.0.0.0/0` or `::/0`, such as `0.0.0.0/1` plus `128.0.0.0/1`, as open to the internet; such a rule used to pass `ec2_securitygroup_allow_ingress_from_internet_to_tcp_port_22` and its siblings. Contributed by @harshrajdebug. Thank you! Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### 🛠️ Improvements and Fixes * Every MCP Server tool declares `readOnlyHint` and `destructiveHint`, so clients can tell a listing from a write when deciding whether to ask the user. Mutelist and mute rule writes are marked destructive because they hide findings for good. * The cross-provider compliance tab keeps the frameworks that loaded, with a warning, when one catalog page or framework fails, instead of going blank. * The NATO D32 compliance framework has its own icon on the compliance cards. * Lighthouse AI replies no longer blink when the response finishes streaming, and the user avatar no longer requests the current page as an image, which rendered every page twice. * The Invitations page uses **Status** instead of **State**, and the Invitations and Roles filters show capitalized options. * **Prowler Cloud:** actions refused because the tenant is over its plan's usage limit, such as launching a scan, saving a schedule, adding a provider or triaging a finding, now link to the plans page. * **Prowler Cloud:** creating API keys is a Prowler Cloud feature; on Local Server the button opens the upgrade dialog, and existing keys can still be edited and revoked. * **Prowler Cloud:** issue evaluation after a scan reads the scan's findings through their indexes instead of a server-side cursor that took hours on large scans, so the evaluations no longer queue up behind each other. * **Prowler Private Cloud:** Lighthouse AI can use Amazon Bedrock with only a region, relying on the installation's own AWS role, when the API allows it. ### 🔐 Security Updates * `pymongo` upgraded to 4.18.3, `dnspython` to 2.9.0 and `oauthlib` to 4.0.0 in the SDK and the API container image, patching the BSON decoding and DNS compression pointer denial of service advisories and the OAuth device flow token disclosure. The API also moves `django-allauth` to 65.19.7, since earlier releases cap `oauthlib` below 4. * `Authlib` upgraded to 1.9.1 and `dnspython` to 2.9.0 in the MCP Server container image, patching CVE-2026-96760 (critical), CVE-2026-114615, CVE-2026-114616 and CVE-2026-114605. ### 🙌 External Contributors Thank you to our community contributors for this release! * @BabafemiB: Azure `network_application_gateway_waf_enabled`, `network_application_gateway_http2_enabled` and `iam_subscription_owners_between_2_and_3` checks ([#13160](https://github.com/prowler-cloud/prowler/pull/13160), [#13145](https://github.com/prowler-cloud/prowler/pull/13145)) * @harshrajdebug: AWS security group internet exposure fix for split CIDRs ([#13191](https://github.com/prowler-cloud/prowler/pull/13191)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.47.0) for the complete list of changes. **v5.46.0** October 26, 2026 ### 🎯 Issues — Attack Paths with an Exploitability Verdict > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). A scan returns a list of failed checks, and most of them are one problem seen from several angles. The new **Issues** page folds the failed findings of each account into attack paths and gives each one a verdict: `exploitable`, `likely`, `conditional`, `not_exploitable` or `unknown`. The verdict is drawn from five legs of evidence (reachability, access, target, controls and verification), each naming the checks and resources it was read from, so a reader can disagree with it instead of having to trust it. A control in force moves a verdict one rung down and the issue says which control did it; a check that did not run reads as `unknown`, never as safe. * Patterns cover AWS, Azure, GCP and Microsoft 365 and are keyed on Prowler check IDs, so detection is never reimplemented. Six more AWS paths ship in this release: Lambda functions anyone can invoke, snapshots shared with every AWS account, instances that can leak their role's credentials, database ports open to the internet, stale or weakly protected IAM user credentials, and roles another AWS account can use. * Each issue says what the path buys an attacker and where the attacker has to start, lists the compliance frameworks its findings put at risk, and can be sent to Jira as one grouped ticket. * An attack path can be triaged with a status and notes from its detail. The decision is kept per account and pattern, so it survives the next scan, which marks it resolved when the path is gone and reopened when it comes back. * The issue list opens with summary tiles and names the account of each issue, so two accounts with the same misconfiguration no longer read as one row. Each issue shows its risk factors, the triage status of every folded finding and an issue graph that starts internet-facing paths at the Internet node, drawn only where a reachability check failed on the resource, and has a page of its own to share. * The Overview shows a verdict share card and the top issues with their risk factors, with counts scoped to the latest completed scan of each provider. * **API:** `GET /api/v1/issues`, `GET /api/v1/issues/{id}` and `GET /api/v1/issues/overview`, with `filter[outcome__in]`, `filter[attacker_start__in]` and `filter[triage_status__in]`; triage lives at `/api/v1/issues/{id}/triage` and `/api/v1/issues/{id}/triage/notes`. ### 🐘 PHP — Coverage After the October Security Release The PHP project shipped an emergency release on October 21 fixing two unauthenticated remote code execution flaws (CVE-2026-109618, CVE-2026-109619), with no fix for 8.1 and older branches. Four new checks cover how each cloud exposes the runtime, and the Azure runtime checks no longer fail every version newer than the configured one. * **AWS:** `elasticbeanstalk_environment_php_platform_updated` flags PHP environments on branches without security fixes or on platform versions older than the one bundling the fixed release, `lightsail_instance_php_blueprint_updated` reports instances created from PHP blueprints for manual verification, and `wafv2_webacl_managed_rule_groups_enabled` verifies that a Web ACL references at least one managed rule group. * **GCP:** new `appengine` service and `appengine_version_php_runtime_supported` check, flagging App Engine serving versions on PHP runtimes without security fixes. * **Azure:** `app_ensure_php_version_is_latest`, `app_ensure_python_version_is_latest` and `app_ensure_java_version_is_latest` now pass any runtime at or above the configured minimum, and the default `php_latest_version` is raised from `8.2` to `8.5` in the SDK and in the scan configuration template of Prowler App. The version thresholds are configurable; see the [configuration file documentation](https://docs.prowler.com/user-guide/cli/tutorials/configuration_file). ### 🧠 GCP — Vertex AI Workbench Coverage A new Vertex AI service audits Workbench instances with five checks, all contributed by @rajeshnadiminti. Thank you! * `vertexai_workbench_instance_public_ip_disabled` and `vertexai_workbench_instance_root_access_disabled`, mapped to PCI DSS 4.0. * `vertexai_workbench_instance_terminal_access_disabled`, `vertexai_workbench_instance_file_download_disabled` and `vertexai_workbench_instance_auto_upgrade_enabled`, with the Workbench checks mapped to the CCC MLDE requirements. ### 🤖 AWS — Bedrock and Cognito Checks * `bedrock_guardrail_sensitive_information_filter_enforced` flags guardrails whose PII entities or custom regexes take no action on the output path, so a detected match is reported in the trace and still delivered to the caller. Contributed by @tamg-aws. Thank you! * `bedrock_model_invocation_logging_text_data_enabled` verifies that model invocation logging delivers prompt and response text rather than naming a destination while excluding request and response bodies. Contributed by @tamg-aws. Thank you! * `cognito_user_pool_account_recovery_sms_not_preferred` verifies that user pools do not rank SMS first for account recovery. Contributed by @UTKARSH698. Thank you! * `bedrock_api_key_no_long_term_credentials` now reports long-term API keys that never expire; IAM only returns `ExpirationDate` for keys created with an expiration period, so keys created without one produced no finding at all. Also contributed by @tamg-aws. Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### 📬 Google Workspace — Policy Precedence and Edition Context * Checks now read the policy Google applies (the greatest `sortOrder`) instead of the last policy the Cloud Identity Policy API lists, which reported default values over admin-configured ones. * Checks for Chat, Drive, Gmail, Calendar and Groups pass with the reason stated when the app is turned off for everyone and no organizational unit or group turns it back on. Drive sharing settings and the settings of existing groups keep being evaluated, because existing shares and groups stay reachable. * Findings state when a feature is not sold on the tenant edition, such as Drive DLP rules, Google session control and the shared drive sharing settings on Business Starter. Reading editions needs the optional `apps.licensing` scope; see the [authentication documentation](https://docs.prowler.com/user-guide/providers/googleworkspace/authentication). * The Gmail spoofing checks read each protection action from its own Policy API field: the inbound domain spoofing check could never pass and the similar domain names check reported the inbound action. * `drive_publishing_files_disabled` passes when sharing outside the organization is limited to allowlisted domains or off, and `drive_desktop_access_disabled` remediation points to the Google Drive for desktop card in the Admin console. ### 🛠️ Improvements and Fixes * Scan report generation parses each resource's metadata once per batch, sanitizes it once per finding and releases each batch before building the next one, so providers with very large resource metadata no longer exhaust the worker memory. * Scan ingestion compares the serialized resource metadata with the stored value and serializes sets in a stable order, so unchanged resources no longer get their metadata, details and `updated_at` rewritten on every scan. * The compliance report PDF cover table wraps every value, so long account IDs such as OCI tenancy OCIDs no longer overflow their cell. * **Launch an initial scan now** is ticked by default on the provider and organization setup launch steps, so saving a schedule also runs a first scan unless the box is unticked. * The SAML SSO integration card on the profile page is shown to roles with the Manage Account permission, matching the API requirement. * **Prowler Cloud:** the scan-reports worker replaces each Celery child process after one report, so the memory a large report needs is returned instead of pushing the task towards an out-of-memory kill, and a container health check replaces a worker that stops consuming instead of leaving it in steady state. * **Prowler Cloud:** persistent report, compliance and overview workers no longer shut themselves down when a task named like a scan hits its time limit or is revoked; the one-shot shutdown only applies to the ephemeral workers of the `scans` queue. ### 🔐 Security Updates * Resource metadata attached to findings no longer carries the values that secrets checks scan (CloudFormation outputs, Lambda environment variables, EC2 user data and similar fields); they are replaced with `REDACTED` before reaching the Evidence tab, the API and the output files. * SAML SSO configuration endpoints require the `manage_account` permission instead of `manage_integrations`, since the configured IdP controls who signs in and which role they receive. * Attack Paths custom queries strip block comments before the blocked-operation check and drop APOC virtual nodes and relationships from results, so `LOAD CSV` can no longer be split with a comment nor its response returned under a forged provider label. * `GET /resources/metadata`, `GET /resources/metadata/latest`, `GET /findings/metadata` and `GET /findings/metadata/latest` honour the provider groups of the caller role instead of aggregating every provider in the tenant. * OpenStack `auth_url` values resolving to loopback, private or otherwise non-public hosts are rejected before the SDK connects, on both the connection test and the scan. * `djangorestframework` upgraded to 3.18.3 in the API, patching the JSON parser charset and Accept header denial of service and the TokenProxy revocation bypass. * `Pillow` upgraded to 13.0.0 in the API, patching a JPEG decoder heap overflow. * `certifi` upgraded to 2026.10.19 in the SDK, the API and the MCP Server, dropping the emSign root CAs whose intermediate keys were compromised, and `uv` to 0.13.4 in the SDK and API images for the same reason. * `aiohttp` upgraded to 3.14.5 with `yarl` 1.25.1 in the SDK and the API, patching the aiohttp resource exhaustion advisories. * `black` upgraded to 26.10.1 and `graphql-core` to 3.2.12 in the SDK, patching CVE-2026-114134, CVE-2026-75507 and CVE-2026-75508, and `libbrotli1` to 1.1.0-2+deb13u1 in its container image, patching CVE-2026-111497. * Trivy upgraded to 0.76.1 in the SDK and API images, patching the HTTP/2, TLS and Go 1.27.2 stdlib CVEs bundled in Trivy 0.75.0, and the SDK and API images no longer ship the MicrosoftTeams build SBOM that Trivy read as installed `zod` and `body-parser`. * `next` upgraded to 16.4.1 in the UI, patching two unauthenticated remote code executions (Image Optimization with SVG files, GHSA-2464-fhr4-w9xw; `use cache` functions returning typed arrays, GHSA-673q-mjm6-r5xr), `@sentry/nextjs` to 10.75.2 for the middleware bypass through the tunnel route (GHSA-mchm-gjx6-7h55) and DOMPurify to 3.4.17 for the `SAFE_FOR_TEMPLATES` bypass (GHSA-cg2g-xh64-v4q7). * Node.js upgraded to 24.22.1 LTS in the UI container image, patching the eight CVEs of the October 2026 security release that affect the 24.x line, including the Brotli decoder remote code execution (CVE-2026-111497); the base image moves to Alpine 3.24. ### 🙌 External Contributors Thank you to our community contributors for this release! * @rajeshnadiminti: GCP Vertex AI service and its Workbench checks ([#13062](https://github.com/prowler-cloud/prowler/pull/13062), [#13077](https://github.com/prowler-cloud/prowler/pull/13077)) * @tamg-aws: AWS `bedrock_guardrail_sensitive_information_filter_enforced` and `bedrock_model_invocation_logging_text_data_enabled` checks and the `bedrock_api_key_no_long_term_credentials` fix ([#12663](https://github.com/prowler-cloud/prowler/pull/12663)) * @UTKARSH698: AWS `cognito_user_pool_account_recovery_sms_not_preferred` check ([#12251](https://github.com/prowler-cloud/prowler/pull/12251)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.46.0) for the complete list of changes. **v5.45.0** October 15, 2026 ### 🤖 Azure — AI Services Coverage A new Azure AI Services service audits the Azure AI and Azure OpenAI accounts of each subscription, with nine checks across network exposure, authentication, encryption, identity, logging and content safety, all contributed by @rajeshnadiminti. Thank you! * `aiservices_account_public_network_access_disabled`, `aiservices_account_network_acls_default_action_deny`, `aiservices_account_uses_private_endpoint` and `aiservices_account_outbound_network_restricted` cover how the account can be reached and what it can reach. * `aiservices_account_local_auth_disabled` and `aiservices_account_managed_identity_enabled` cover key-based access and the account's own identity. * `aiservices_account_encrypted_with_cmk` and `aiservices_account_diagnostic_logging_enabled` cover customer-managed key encryption and diagnostic logs. * `aiservices_deployment_content_filter_prompt_shield_enabled` verifies that model deployments have Prompt Shields enabled in their content filter. ### 🪪 Microsoft 365 — New Entra ID Checks Five new Entra ID checks, all contributed by @kinomakino. Thank you! * `entra_cross_tenant_access_default_outbound_restricted` verifies that the default cross-tenant access policy does not let every user reach every external application through B2B collaboration or B2B direct connect. * `entra_policy_admin_self_service_password_reset_disabled` verifies that Self-Service Password Reset is disabled for administrators. * `entra_policy_msol_powershell_blocked` verifies that the tenant authorization policy blocks the legacy MSOnline PowerShell module. * `entra_app_registration_redirect_uris_secure` flags app registrations with HTTP, wildcard, malformed or `azurewebsites.net` redirect URIs. * `entra_dynamic_group_member_of_rule_not_used` flags dynamic groups whose membership rule uses the `memberOf` operator, which Microsoft retires on November 3, 2026. Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### ☁️ OCI — Connect Tenancies Outside us-ashburn-1 OCI API key credentials now take a home region, and the credentials form in Prowler App requires it. Identity calls that validate the credentials and discover the subscribed regions used to go to `us-ashburn-1` regardless of the tenancy, so a tenancy not subscribed to that region could not connect. The home region is only used for that bootstrap; scans still audit every subscribed region. Read more in the [Getting Started with OCI documentation](https://docs.prowler.com/user-guide/providers/oci/getting-started-oci). ### 🛠️ Improvements and Fixes * **AWS:** Organizations metadata is fetched from the partition of the audited account, using the region that answered the STS bootstrap, instead of the commercial `us-east-1` endpoint, which timed out in GovCloud. * API Gunicorn workers are recycled after 10,000 requests, plus up to 1,000 of jitter, to cap memory growth. Both values are configurable with `GUNICORN_MAX_REQUESTS` and `GUNICORN_MAX_REQUESTS_JITTER`. * The first-login redirect to the Add Provider wizard is retried on the next load when the navigation was cut short, instead of being written off after a single attempt. * The AWS connect step offers to invite a teammate when the user cannot access the account credentials. * **Prowler Cloud:** the Slack channel picker reads the channels the Prowler app is in before the public ones, so invited private channels show up in large workspaces, and the partial list message tells the user to invite the app to a missing channel. ### 🔐 Security Updates * Kubernetes kubeconfigs accept only inline credentials and known cluster fields. File-path fields, command-based authentication, `auth-provider` directives, proxy URLs and unknown keys are rejected by the API and the credentials form, and stored kubeconfigs are re-validated before each scan and connection test. * IaC repository URLs that resolve to loopback, private or otherwise non-public hosts are rejected before the connection test and the scan clone, including every destination a redirect points to. * CSV outputs prefix cells starting with `=`, `+`, `-`, `@`, tab or carriage return with a single quote so spreadsheet applications treat them as text, and the HTML report escapes the compliance column. * `GET /api/v1/users/{id}` no longer exposes another user's memberships, roles or tenant names from tenants other than the one in the request token. * API error reports sent to Sentry no longer include user identity, IP addresses, cookies, headers or request bodies. * PowerShell upgraded to 7.5.12 in the SDK and API container images, bundling .NET runtime 9.0.21. * Python base images upgraded to 3.12.15 in the SDK and API and to 3.13.16 in the MCP Server, and Trivy to 0.75.0, patching CVE-2026-19445, CVE-2026-19553 and the grpc-go and x/crypto CVEs bundled in Trivy. * `django` upgraded to 5.2.17 in the API, patching CVE-2026-15307. * `pyjwt` upgraded to 2.14.0 in the SDK, the API and the MCP Server, patching GHSA-ffc3-869f-jxw9. * `pymongo` upgraded to 4.18.2 and `urllib3` to 2.8.0 in the SDK and the API, patching CVE-2026-96748, CVE-2026-96749, CVE-2026-97687 and CVE-2026-97689. * `dulwich` upgraded to 1.2.9 in the SDK and the API, patching GHSA-5fqc-mrg8-w798, GHSA-8mcx-5rqc-vhmf, GHSA-8w8g-wq8h-fq33 and GHSA-cm62-gvxx-vmxx. * `next` upgraded to 16.3.8 in the UI, patching a remote code execution in `next/og` (GHSA-vcvr-r3jv-pc5j) and a server-side request forgery in Image Optimization (GHSA-cjq9-62q9-8jv4). * `sharp` upgraded to 0.35.5 and `proxy-addr` to 2.0.8 in the UI, patching GHSA-wq5f-xc86-pv6w and GHSA-jqcg-44mw-7w3h. ### 🙌 External Contributors Thank you to our community contributors for this release! * @rajeshnadiminti: Azure AI Services service and its checks ([#12925](https://github.com/prowler-cloud/prowler/pull/12925), [#12926](https://github.com/prowler-cloud/prowler/pull/12926), [#12997](https://github.com/prowler-cloud/prowler/pull/12997)) * @kinomakino: Microsoft 365 `entra_cross_tenant_access_default_outbound_restricted` ([#12991](https://github.com/prowler-cloud/prowler/pull/12991)), `entra_policy_admin_self_service_password_reset_disabled` ([#12990](https://github.com/prowler-cloud/prowler/pull/12990)), `entra_policy_msol_powershell_blocked` ([#13004](https://github.com/prowler-cloud/prowler/pull/13004)), `entra_app_registration_redirect_uris_secure` ([#12993](https://github.com/prowler-cloud/prowler/pull/12993)) and `entra_dynamic_group_member_of_rule_not_used` ([#13003](https://github.com/prowler-cloud/prowler/pull/13003)) checks See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.45.0) for the complete list of changes. **v5.44.0** September 29, 2026 ### 🔁 Findings — Re-check a Resource with a Partial Scan > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). A resource that has just been fixed can be confirmed from the Findings page without waiting for the next full scan. **Re-check resource** is available in the actions menu of every resource row and in the resource detail drawer, and a hint icon next to **Last seen** opens it directly. It launches a partial scan that runs again only the checks that last reported on that resource; its findings update when the scan completes, and every other resource keeps the results of the latest full scan. Roles need the Manage Scans permission, and a re-check is refused while the provider has a scan running or queued. Re-checked resources that now pass drop out of the finding groups list and its drill-down instead of opening a detail panel that still reports `FAIL`. Partial scans do not change overviews or compliance until the next full scan and produce no report files, so the Scans table marks them as **Partial**, offers no report download for them, and the per-scan Compliance selector leaves them out. Partial scans can also be launched outside the Findings page: * **API:** `POST /api/v1/scans` accepts up to 10 resources in `resource_uids`, and scans expose `is_partial` with a `filter[is_partial]` filter. * **MCP Server:** `prowler_trigger_scan` takes a `resource_uids` argument, and `prowler_list_scans` and `prowler_get_scan` return `is_partial`, with an `is_partial` filter on `prowler_list_scans`. * **Lighthouse AI:** can launch a partial scan to re-check specific resources, such as confirming a remediation. ### ☁️ AWS — Connect an Account in One Step The Add Provider wizard connects an AWS account in a single step. The account ID is read from the role ARN (or typed when using static access keys), the role is assumed with Prowler's own credentials, and the account, its credentials and the connection test are handled by one submit. A confirmed connection goes straight to the launch step. A refused connection stays on the form with the reason the API returned, so the fields can be fixed and retried without registering the account twice. New tenants without providers now land on this wizard on their first sign-in instead of a welcome modal, and the sidebar action reads **Add Provider** until the first provider is connected. Read more in the [Getting Started with AWS documentation](https://docs.prowler.com/user-guide/providers/aws/getting-started-aws). ### 🔌 Connection Tests No Longer Give Up Early The provider connection test no longer reports `Max retries exceeded` for checks that take longer than 30 seconds, such as networks where some AWS endpoints are unreachable. The UI now waits for the full time limit of the backend task, and if that is still exhausted it shows the provider's current connection state instead of a failure. On the SDK side, STS calls after a role assumption reuse the region that answered, so an unreachable partition region is waited on once instead of twice. The new `PROWLER_AWS_BOTO3_RETRIES_MAX_ATTEMPTS` environment variable sets the Boto3 retries for deployments that build the AWS provider without CLI flags, next to the existing timeout variables; `0` disables retries. Read more in the [Boto3 configuration documentation](https://docs.prowler.com/user-guide/providers/aws/boto3-configuration#retries-configuration). ### 🗄️ Self-Hosted — S3-Compatible Storage and Air-Gapped Deployments * `DJANGO_OUTPUT_S3_AWS_ENDPOINT_URL` points scan output uploads and downloads at S3-compatible object storage such as MinIO. Previously the only way to reach it was exporting process-wide AWS environment variables, which also hijacked unrelated AWS API calls such as role assumption for AWS providers. * Report downloads from a bucket with default SSE-KMS encryption no longer fail with `InvalidArgument`: when `DJANGO_OUTPUT_S3_AWS_DEFAULT_REGION` is set, download URLs are signed with Signature Version 4 for that region. * Icons ship in the UI bundle instead of being fetched from `api.iconify.design`, so pages render correctly without internet access. * Celery worker fatal errors are logged instead of silenced, and every long-running service in `docker-compose.yml` restarts automatically after an unexpected crash. ### 📊 Consistent Latest Scan Across Endpoints Every endpoint now resolves a provider's latest completed scan the same way, so overlapping scans no longer make findings, compliance and mute rules read from different scans. Providers whose latest completed scan has no `completed_at` timestamp are no longer missing from those endpoints, and resources no longer keep a stale failed findings count when a scoped or imported scan completes after a full scan. ### 🛠️ Prowler App Fixes * API key authentication no longer locks the key row on every request, so a heavily used key no longer serializes all its requests; `last_used_at` is updated at most once per minute. * `POST /api/v1/scans` returns the new scan ID in `task_args` again. * Provider deletion no longer fails when the provider has Attack Paths scans recorded on a sink that is no longer configured, such as Neptune after moving back to Neo4j. * A periodic sweep drops orphaned Attack Paths temporary Neo4j databases left behind when a worker or Neo4j crashes mid-scan. * **Prowler Cloud:** imported findings no longer stay stuck in `pending` when the ingestion worker picks up the job before it is committed, and a failed enqueue marks the ingestion as failed. * **Prowler Cloud:** the Lighthouse AI connection check reports a network failure as one, naming the endpoint it could not reach, instead of hitting a time limit that looked the same as a bad key. * **Prowler Cloud:** the finding groups endpoints no longer query Manual Pass triages once per finding, and skip that overlay for tenants with no active Manual Pass. * The Findings page renders a skeleton at once and streams the table before the filters, and the **Finding Group** options load when the dropdown opens. * Mute rule creation errors show the API error message instead of the raw response body. * The sidebar no longer throws a hydration error on full page loads for users who last used the chat mode. ### 🔐 Security Updates * `DELETE /api/v1/tasks/{id}` requires the permission of the operation that queued the task and rejects provider deletions, and `GET /api/v1/tasks` hides tasks of providers outside the role's visibility. * The UI E2E workflow receives its AWS credentials through environment variables instead of template expansion. See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.44.0) for the complete list of changes. **v5.43.0** September 21, 2026 ### 🏛️ Compliance — FedRAMP 20x Consolidated Rules 2026 The FedRAMP 20x Phase One pilot frameworks (`fedramp_20x_ksi_low_aws`, `fedramp_20x_ksi_low_azure` and `fedramp_20x_ksi_low_gcp`) are replaced by two universal frameworks built from the FedRAMP Consolidated Rules for 2026, each covering AWS, Azure, GCP, Kubernetes and Microsoft 365 from a single definition: * **FedRAMP 20x KSI** (`fedramp_20x_ksi_2026`): the 46 Key Security Indicators across 10 themes. There is one indicator catalog for every class instead of a separate Low fork; each indicator carries its class applicability and NIST SP 800-53 controls. * **FedRAMP 20x Class C FRR** (`fedramp_20x_frr_class_c_2026`): the 158 FedRAMP Rules of the Class C ruleset that bind cloud service providers. Most are program obligations (reports, notifications, certification package) and stay manual; checks are mapped only where they evidence part of the rule text. Configurable checks carry configuration requirements, so a relaxed `audit_config` cannot turn a requirement green. Automation or stored results that reference the pilot framework IDs need to move to `fedramp_20x_ksi_2026`. In Prowler App, both frameworks show the per-provider breakdown in the cross-provider compliance view and can be downloaded as OCSF. Read more in the [Compliance documentation](https://docs.prowler.com/user-guide/compliance/tutorials/compliance). ### 🔎 AWS — Inspector Coverage, CISA KEV and FIPS Checks Seven new AWS checks back the vulnerability detection and cryptography rules of FedRAMP 20x Class C: * `inspector2_coverage_scan_status_active` and `inspector2_coverage_recently_scanned` report resources Amazon Inspector is not scanning, or last scanned more than `inspector2_max_days_since_last_scan` days ago (default 3). * `inspector2_active_findings_no_known_exploited_vulnerabilities` and `inspector2_active_findings_kev_within_due_date` report active findings whose CVE is in the CISA Known Exploited Vulnerabilities catalog, and those still open past the CISA due date. The KEV data comes from Inspector itself through `inspector2:BatchGetFindingDetails`, so no external feed is needed. * `inspector2_active_findings_within_max_age` reports active findings first observed more than `inspector2_active_finding_max_age_days` days ago (default 192). * `elbv2_listener_fips_tls_enabled` and `transfer_server_fips_security_policy_enabled` report HTTPS/TLS load balancer listeners and Transfer Family servers without a FIPS security policy. `inspector2:BatchGetFindingDetails` is not part of `SecurityAudit`, so it is now included in the Prowler additions policy and the CloudFormation scan role. Without it, the KEV checks report `MANUAL` naming the missing permission instead of a false `FAIL`. Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). ### ☁️ AWS — Partition Bootstrap Failover When `PROWLER_AWS_PARTITION` is set, the bootstrap STS calls (validating credentials, assuming a role and getting an MFA session token) now try up to two more regions of the partition if the first one cannot be reached. A GovCloud host whose configured region belongs to another partition was still sent to `us-gov-east-1`, and on a network that routes only to `us-gov-west-1` the connection check and the scan failed on perfectly valid credentials. Only connection errors and timeouts move on to the next region; credential errors are reported from the first one as before. Later STS calls reuse the region that answered, and nothing changes when `PROWLER_AWS_PARTITION` is unset. Read more in the [AWS Regions and Partitions documentation](https://docs.prowler.com/user-guide/providers/aws/regions-and-partitions). ### 🌐 Azure — Sovereign Cloud Endpoints for Defender and Key Vault Defender security contacts and Key Vault key rotation policies now use the endpoints of the cloud selected with `--azure-region` instead of the hardcoded `management.azure.com` and `vault.azure.net` hosts, so both work on `AzureUSGovernment` and `AzureChinaCloud`. Key Vault clients are built from the vault URI that Azure returns for each vault. Read more in the [Azure non-default cloud documentation](https://docs.prowler.com/user-guide/providers/azure/use-non-default-cloud). ### ✉️ Invitations — Expired Invitations No Longer Block Re-Invites A pending invitation past its expiry date is now reported as expired, and inviting the same email again marks it as expired and creates the new invitation instead of returning a generic error. The Invitations table disables Edit and Revoke on expired and revoked invitations, and `filter[state__in]` on the invitations endpoint no longer returns a server error. In Prowler Cloud, new organizations are offered an **Invite your team** step once the first provider is connected, and Prowler Private Cloud deployments can set `UI_SELF_REGISTRATION_ENABLED=false` to make sign-up invitation-only. Read more in the [Invitations documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-rbac#invitations). ### 📄 Reports — Downloads on Self-Hosted Storage Report downloads no longer depend on the storage host being the same inside and outside the container network. `DJANGO_OUTPUT_S3_AWS_PUBLIC_ENDPOINT_URL` signs the download URL against a browser-reachable host, so a deployment whose object storage answers only on an internal address serves the file instead of a link the browser cannot open. Leaving `DJANGO_OUTPUT_S3_AWS_DEFAULT_REGION` unset, common on S3-compatible storage with no meaningful region, no longer makes the download fail with a server error. ### 🔍 Checks * **Huawei Cloud:** new `smn_topic_subscriptions` check reports SMN topics without any subscription. * **Cloudflare:** the API token links in the provider wizard request the SSL and Certificates, Bot Management and Zone WAF read permissions the checks need, so a token created from the wizard no longer produces failures on permissions it was never granted. * **Microsoft 365:** five Defender malware, anti-phishing and inbound anti-spam checks no longer fail with `KeyError` on tenants that use the Standard or Strict preset security policies, which dropped every finding of those checks. Preset policies are covered by `defender_strict_preset_security_policy_enabled`. * **Google Workspace:** `security_2sv_enforced` reports domain-wide 2-Step Verification failures as `FAIL` even when every failing setting is overridden for a group or organizational unit. Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### 🔐 Security Updates * `libsqlite3-0`, `gzip`, `perl-base`, `libssh2-1t64` and `libpcre2-8-0` upgraded in the SDK and API container images, patching high-severity Debian CVEs. * PowerShell upgraded to 7.5.11 in the SDK and API container images, bundling .NET runtime 9.0.20 and patching CVE-2026-62901. * `anyio` upgraded to 4.14.2 in the SDK, the API and the MCP Server, patching CVE-2026-63374. See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.43.0) for the complete list of changes. **v5.42.0** September 11, 2026 ### ☁️ AWS — ISO Partitions Prowler now resolves regions and services for the AWS ISO partitions (`aws-iso`, `aws-iso-b`, `aws-iso-e` and `aws-iso-f`) the same way it does for the commercial, China, European Sovereign Cloud and GovCloud partitions. The region matrix is filled from the endpoint metadata bundled with botocore, which needs no credentials or network access, so it covers partitions that are air-gapped from the internet. Scanning them no longer requires a hand-edited `aws_regions_by_service.json`: ISO regions such as `us-isob-east-1` are accepted by `--region` and `--excluded-region`. Deployments that declare `PROWLER_AWS_PARTITION` also keep their bootstrap STS calls in the configured region when it belongs to that partition. An install in `us-gov-west-1` that reaches AWS only through its own VPC endpoints is no longer sent to `us-gov-east-1`, where the connection check and the scan used to time out. Read more in the [AWS Regions and Partitions documentation](https://docs.prowler.com/user-guide/providers/aws/regions-and-partitions). ### ⏱️ AWS — Configurable Timeouts for Restricted Networks Scans from networks with restricted egress (VPC endpoints for only some services, GovCloud or private deployments) could take hours: Boto3 waits 60 seconds to connect by default and retries connection errors, so every service without a reachable endpoint cost up to four 60-second attempts in every region. Prowler now lowers the default connect timeout to 10 seconds, keeps the read timeout at 60 seconds, and exposes both through `--aws-connect-timeout` and `--aws-read-timeout`, or through the `PROWLER_AWS_BOTO3_CONNECT_TIMEOUT` and `PROWLER_AWS_BOTO3_READ_TIMEOUT` environment variables for deployments without a CLI. `--aws-retries-max-attempts 0` now disables retries instead of silently falling back to three, leaving a single attempt per call. Read more in the [Boto3 configuration documentation](https://docs.prowler.com/user-guide/providers/aws/boto3-configuration). ### 🐳 Image Provider — Reusable Vulnerability Database The Image provider now honors `TRIVY_CACHE_DIR`. When the variable names a directory, Trivy keeps its vulnerability database there and Prowler leaves the directory in place after the scan, so the database is downloaded once instead of on every scan. Hosts without internet access can now scan images by pointing `TRIVY_CACHE_DIR` at a pre-populated database and setting `TRIVY_SKIP_DB_UPDATE=true`. Without the variable, the temporary cache is created and removed as before. Read more in the [Image provider documentation](https://docs.prowler.com/user-guide/providers/image/getting-started-image#vulnerability-database-cache). ### 🎫 Jira Integration — Faster Connection Test Testing a Jira integration no longer reports a false failure on accounts with many projects. The connection test fetched the issue types of every project one request at a time, which could outlast the wait in the UI even when the check was about to succeed. Issue types are now fetched concurrently, a project whose issue types the integration user cannot see is no longer logged as an error, and the Integrations page keeps following the connection test instead of giving up after about a minute. Read more in the [Jira integration documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-jira-integration). ### 📚 Compliance — Catalog Integrity Fixes A new integrity test runs over every compliance framework, asserting unique requirement IDs, no check listed twice within a requirement, and that every referenced check exists for its provider. The fixes it drove span 42 frameworks across AWS, Azure, GCP, GitHub, Kubernetes and Microsoft 365: * **Duplicate requirement IDs:** identical copies are removed, and distinct requirements that shared an ID get their own, such as `1.10` in CIS AWS 5.0 and `rc_rp_1` for RC.RP-1 in NIST CSF 1.1. In Prowler ThreatScore for Azure, SQL auditing retention moves from `3.2.1` to `3.2.4`, and requirement `1.2.1` of Prowler ThreatScore for GCP now points to `iam_sa_no_user_managed_keys`. * **Stale check references:** checks that no longer exist are replaced with their current name when there is a direct equivalent, or removed so the requirement reports as manual. Most of these were in the FedRAMP 20x KSI frameworks. Renamed requirement IDs appear as new requirements for scans run after the upgrade. The compliance overview task that runs after every scan is also faster: ThreatScore mappings are read once from the compliance template instead of from every finding, and rows are inserted with time-ordered `uuid7` IDs grouped by framework and requirement. Read more in the [Compliance documentation](https://docs.prowler.com/user-guide/compliance/tutorials/compliance). ### 🔍 Checks `rolesanywhere_profile_restricts_session_permissions`, `iam_role_service_trust_restricts_source_to_account` and `codebuild_project_uses_allowed_github_organizations` no longer crash with `TypeError` when the scanning role is denied `iam:ListRoles`, which dropped every finding of those checks for the account. Without the role inventory, an enabled IAM Roles Anywhere profile without session scoping reports `MANUAL`, and CodeBuild projects whose service role cannot be resolved are skipped. Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). ### 🔐 Security Updates * `next` upgraded to 16.3.3 in the UI, patching unauthenticated remote code execution through AVIF image optimization ([GHSA-2xp9-vwfh-vxw4](https://github.com/advisories/GHSA-2xp9-vwfh-vxw4)) and on Windows-hosted servers ([GHSA-p293-qw3h-jr36](https://github.com/advisories/GHSA-p293-qw3h-jr36)). * `sharp` upgraded to 0.35.4 in the UI, patching libheif image-decoding vulnerabilities ([GHSA-rgj7-g3m4-5g8c](https://github.com/advisories/GHSA-rgj7-g3m4-5g8c)). * `nanoid`, `js-yaml` and `postcss`, plus eleven transitive UI dependencies, upgraded to patched versions, resolving 40 npm audit advisories (21 high, 15 moderate, 4 low). * `libuuid` upgraded to 2.41.6-r1 in the MCP Server image, patching CVE-2026-53612, CVE-2026-53613, CVE-2026-53614, CVE-2026-76642, CVE-2026-78408 and CVE-2026-78410. See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.42.0) for the complete list of changes. **v5.41.0** September 2, 2026 ### 📥 Scans — Import Findings from the Browser > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Findings produced outside the platform, by the Prowler CLI or a CI pipeline, can now be brought into the app without leaving the browser. The Scans page gains an "Import Findings" dialog that takes a Prowler `.ocsf.json` report by drag-and-drop or file picker, hands it to the ingestion API and tracks the job to completion, reporting how many records were processed and how many were invalid. Files that are not a `.ocsf.json` report, or are empty, are refused before any upload starts, and a rejected upload or a failed status poll can be retried in place. The dialog is available to roles holding the Manage Ingestions permission. ![Import Findings button on the Scans page](https://mintcdn.com/prowler/IzrY7t1Hmx5RFjXc/images/prowler-app/import-findings/import-findings-button.png?fit=max\&auto=format\&n=IzrY7t1Hmx5RFjXc\&q=85\&s=4aefe03715c8b69d6d4fa65dbe1bed37) ![Import findings dialog with the drag-and-drop area](https://mintcdn.com/prowler/IzrY7t1Hmx5RFjXc/images/prowler-app/import-findings/import-findings-dialog.png?fit=max\&auto=format\&n=IzrY7t1Hmx5RFjXc\&q=85\&s=636071d8f4b77eb82b6821b5cfd44ebe) Read more in the [Import Findings documentation](https://docs.prowler.com/user-guide/tutorials/prowler-import-findings#using-the-ui). ### 🎫 Jira Integration — Finding Reference in Every Issue Every Jira issue created from a finding now carries a stable reference back to it. Issues are labeled `prowler`, `prowler-`, `prowler-`, `prowler-` and `prowler-finding-`, so they can be filtered, searched with JQL or matched by automation; labels are sanitized to Jira's limits so a long or unusual value never blocks issue creation. The issue also links back to the finding in Prowler, filtered by its UID so the link keeps working after later scans, and names the Prowler organization that sent it. Prowler Cloud always includes the link; Prowler Local Server enables it by setting `DJANGO_UI_BASE_URL` in the API environment. Read more in the [Jira integration documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-jira-integration). ### 📚 Compliance — CIS Google Workspace Foundations Benchmark v1.4.0 Prowler now ships the CIS Google Workspace Foundations Benchmark v1.4.0. Alongside the new framework, the Google Workspace checks mapped to CIS were reworked to evaluate the benchmark's full audit procedure instead of a single condition, so Gmail spoofing actions, 2-Step Verification, password expiration and alert severity left on Google's defaults no longer pass. Expect new `FAIL` findings on domains that rely on those defaults. Three accuracy fixes also land: * `security_2sv_enforced` and `security_2sv_hardware_keys_admins` report `MANUAL` instead of judging domain-wide values that a group or a sub-organizational unit overrides; a domain-wide failure is still reported as such, with the override noted. * `rules_*_alert_configured` no longer passes a rule whose delivery to the alert center is disabled. * `security_password_policy_strong` no longer fails a domain that never touched the password strength setting, since Google enforces strong passwords by default. `security_login_challenges_configured` was unmapped from CIS Google Workspace requirement 4.1.4.1 (Post-SSO verification) and `security_2sv_enforced` from CISA SCuBA `GWS.COMMONCONTROLS.1.1` (phishing-resistant MFA), because neither check can prove what those requirements ask for. Read more in the [Compliance documentation](https://docs.prowler.com/user-guide/compliance/tutorials/compliance). ### 🔍 Checks Ten new AWS checks land in this release, eight of them contributed by @tamg-aws. Thank you! #### Amazon Bedrock AgentCore * `iam_policy_passrole_to_bedrock_agentcore_restricted` flags customer-managed IAM policies that allow `iam:PassRole` over every role where the passed role can reach Bedrock AgentCore, so any principal holding the policy could run agent code under any role in the account. * `iam_policy_no_agentcore_workload_access_token_wildcard` flags customer-managed IAM policies that allow `bedrock-agentcore:GetWorkloadAccessToken`, `GetWorkloadAccessTokenForJWT` or `GetWorkloadAccessTokenForUserId` on resources reaching workload identities other than the caller's own. * `cloudwatch_log_group_agentcore_data_protection_policy_enabled` verifies that Bedrock AgentCore log groups mask sensitive data with a CloudWatch Logs data protection policy. The log group prefixes are configurable through `agentcore_log_group_name_prefixes` in `config.yaml`. #### Amazon GuardDuty * `guardduty_runtime_monitoring_enabled` flags detectors without unified Runtime Monitoring, the only feature that covers Amazon EC2 instances and Amazon ECS on AWS Fargate tasks in addition to Amazon EKS. * `guardduty_ai_protection_enabled` flags detectors without AI Protection, which analyzes CloudTrail data events from Amazon Bedrock, Amazon Bedrock AgentCore and Amazon SageMaker AI. A detector that does not report the feature is `MANUAL` rather than `FAIL`. `guardduty_eks_runtime_monitoring_enabled` no longer reports `FAIL` for detectors that use unified Runtime Monitoring, which is mutually exclusive with `EKS_RUNTIME_MONITORING` and already covers Amazon EKS. #### Amazon ECR and EKS * `ecr_registry_enhanced_scanning_enabled` verifies that the ECR registry scan type is enhanced (Amazon Inspector, covering programming language packages and continuous rescanning) instead of basic, reporting `MANUAL` when the registry scanning configuration cannot be read. * `eks_cluster_vpc_cni_network_policy_enforced` flags EKS clusters whose Amazon VPC CNI managed add-on does not enable Kubernetes network policy enforcement, reporting `MANUAL` where the EKS API cannot show the setting. #### AWS IAM, Elastic Beanstalk and MemoryDB * `iam_role_service_trust_restricts_source_to_account` flags IAM roles whose trust policy lets an AWS service principal assume the role without confining the request to a specific source account, including trust policies that `iam_role_cross_service_confused_deputy_prevention` does not evaluate. * `elasticbeanstalk_environment_no_secrets_in_configuration` scans the option settings of every Elastic Beanstalk environment for hardcoded secrets. Thanks to @haneul-24! * `memorydb_cluster_in_transit_encryption_enabled` verifies that MemoryDB clusters have in-transit encryption (TLS) enabled. Thanks to @UTKARSH698! Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). ### 🐳 Image Provider — On-Premises Registries Scanning registries that live on private networks is now supported end to end. `PROWLER_IMAGE_PROVIDER_ALLOWED_PRIVATE_NETWORKS` takes a comma-separated list of IPs and CIDRs the provider may reach, while every other non-public address, including link-local and loopback, stays blocked by the SSRF guard. Authentication negotiation is also more resilient: the provider falls back to Basic when a registry such as Harbor rejects the negotiated bearer token, and switches to a bearer token when the server answers a Basic or anonymous request with a Bearer challenge. `--registry-insecure` now propagates to Trivy through `TRIVY_INSECURE`, so images behind self-signed certificates can be pulled and scanned, not just enumerated. The flag now disables certificate validation for the image pull too, so keep it for trusted internal registries only. Registry scans also skip non-image OCI artifacts (Helm charts, cosign signatures, SBOM attestations), no longer abort the whole scan when Trivy fails on a single image, and enumerate repositories in parallel instead of one request at a time. Read more in the [Image provider documentation](https://docs.prowler.com/user-guide/providers/image/getting-started-image#on-premises-registries-and-private-networks). ### 🛠️ Prowler MCP Server — Tool Failures Reported as Errors Prowler Local Server tools now report a failure as an MCP tool execution error (`isError: true`, with the explanation in `content`) instead of a successful result carrying an `{"error": ...}` object, which clients and models read as a success. The Prowler Documentation and Prowler Hub tools follow the same rule: `prowler_docs_search` no longer reports a failed search as zero matches, `prowler_docs_get_document` no longer reports a failed fetch as a missing page, and `prowler_hub_get_check_code` and `prowler_hub_get_check_fixer` now name the provider a check ID actually belongs to instead of reporting it as nonexistent. `prowler_get_compliance_framework_state_details` also rejects a call that passes both `scan_id` and `provider_id` instead of silently ignoring the provider. Read more in the [Prowler MCP documentation](https://docs.prowler.com/getting-started/products/prowler-mcp). ### 🙌 External Contributors Thank you to our community contributors for this release! * @tamg-aws: GuardDuty unified Runtime Monitoring and AI Protection checks ([#12564](https://github.com/prowler-cloud/prowler/pull/12564)), EKS VPC CNI network policy check ([#12661](https://github.com/prowler-cloud/prowler/pull/12661)), ECR enhanced scanning check ([#12660](https://github.com/prowler-cloud/prowler/pull/12660)), Bedrock AgentCore IAM and service trust checks ([#12664](https://github.com/prowler-cloud/prowler/pull/12664)), AgentCore log group data protection check ([#12662](https://github.com/prowler-cloud/prowler/pull/12662)), and fixes to ECR scan frequency ([#12560](https://github.com/prowler-cloud/prowler/pull/12560)), CloudWatch metric filters ([#12561](https://github.com/prowler-cloud/prowler/pull/12561)) and SageMaker direct internet access ([#12659](https://github.com/prowler-cloud/prowler/pull/12659)) * @haneul-24: AWS `elasticbeanstalk_environment_no_secrets_in_configuration` check ([#12378](https://github.com/prowler-cloud/prowler/pull/12378)) * @UTKARSH698: AWS `memorydb_cluster_in_transit_encryption_enabled` check ([#12246](https://github.com/prowler-cloud/prowler/pull/12246)) * @ye11oc4t: GitHub repository discovery pagination for unscoped scans ([#12460](https://github.com/prowler-cloud/prowler/pull/12460)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.41.0) for the complete list of changes. **v5.40.0** August 28, 2026 ### 💬 Slack Integration — Alert Channel Destinations > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Alerts can now reach Slack. Connect a Slack workspace from the Integrations page, authorize one or several destination channels (the connection check confirms each channel with a one-time message and names any channel Slack refuses), and pick those channels in the alert modal's "Destination channels" selector, next to the "Recipients" selector for email. The alerts list summarizes both in a single "Destinations" column, showing a rule's email recipients and Slack channels at a glance. Disconnecting the workspace and recovering from revoked credentials are handled from the same page. ![Connected Slack workspace on the Integrations page](https://mintcdn.com/prowler/Dhi7Hr6lKPnlWs52/images/prowler-app/slack/connected-workspace.png?fit=max\&auto=format\&n=Dhi7Hr6lKPnlWs52\&q=85\&s=5767e6aef2c88548d447225b52c2c87d) ![Alert rule with Slack channel destinations](https://mintcdn.com/prowler/Dhi7Hr6lKPnlWs52/images/prowler-app/alerts/create-alert-modal.png?fit=max\&auto=format\&n=Dhi7Hr6lKPnlWs52\&q=85\&s=678bd41bc441ef2c0a0bb0e262b7f2fa) Read more in the [Slack integration documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-slack-integration) and the [Alerts documentation](https://docs.prowler.com/user-guide/tutorials/prowler-alerts). ### 🤖 Lighthouse AI — Answer Feedback > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Every Lighthouse AI answer can now be rated with a thumbs up or thumbs down, with an optional field to describe what worked or what did not. Feedback is collected per answer, directly in the chat, and tells the team where Lighthouse should improve next. Read more in the [Lighthouse AI documentation](https://docs.prowler.com/getting-started/products/prowler-cloud-lighthouse). ### 📥 Providers — Imported Findings Indicator > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Providers whose findings were imported with the Prowler CLI now show an "Imported provider" indicator next to their connection status in the providers table. In accounts that mix connected providers with Import Findings uploads, the table now tells them apart at a glance. ![Provider row with the Imported provider indicator and its tooltip](https://mintcdn.com/prowler/wDint2EU7zg5vT87/images/changelog/v5.40.0-imported-provider-indicator.png?fit=max\&auto=format\&n=wDint2EU7zg5vT87\&q=85\&s=2aa30a518aa7ab00129cad4ebe61430d) Read more in the [Import Findings documentation](https://docs.prowler.com/user-guide/tutorials/prowler-import-findings). ### 📚 Compliance — NCSC Cyber Essentials 3.3 Cyber Essentials is the UK National Cyber Security Centre (NCSC) scheme certifying the baseline technical controls an organization must implement, and cloud services are explicitly in scope and cannot be excluded from an assessment. Prowler now includes NCSC Cyber Essentials: Requirements for IT Infrastructure v3.3 (April 2026) as a universal framework, with its 28 requirements organized in the five control themes: Firewalls, Secure Configuration, Security Update Management, User Access Control, and Malware Protection. Sixteen requirements map to Azure checks covering the controls the applicant organization owns under the shared responsibility model. The remaining twelve apply to end-user devices, on-premises network appliances, or organizational process, which cloud control-plane evidence cannot observe, so they are reported as Manual. Contributed by @m-khan-97. Thank you! Read more in the [Compliance documentation](https://docs.prowler.com/user-guide/compliance/tutorials/compliance). ### 🔍 Checks Fifteen new checks land across seven providers in this release. #### AWS * `ecr_repository_image_no_secrets` scans the latest image of each ECR repository, both its configuration and its filesystem layers, for hardcoded secrets. Thanks to @esquaredsec! * Four new Amazon Bedrock checks, thanks to @tamg-aws! * `bedrock_guardrail_contextual_grounding_filter_enabled` verifies that guardrails enable both contextual grounding filters, blocking responses that are not supported by the retrieved source or do not answer the question asked. * `bedrock_custom_model_encrypted_with_cmk` verifies that custom models are encrypted at rest with a customer-managed KMS key instead of an AWS-owned key the organization cannot audit, rotate, or revoke. * `bedrock_knowledge_base_encrypted_with_cmk` verifies that each knowledge-base data source encrypts with a customer-managed KMS key the transient storage used while documents are chunked and embedded. * `bedrock_agent_role_not_shared_across_agents` verifies that every agent has a dedicated execution role, so no agent inherits another's permissions. * `rolesanywhere_profile_restricts_session_permissions` flags IAM Roles Anywhere profiles that reference an administrative role without scoping down the vended session with a session policy or managed policies. Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). #### GCP * `iam_workload_identity_pool_provider_attribute_condition` flags Workload Identity Federation providers that trust a multi-tenant issuer without an attribute condition restricting which external identities can impersonate federated principals. Explore all GCP checks at [Prowler Hub](https://hub.prowler.com/check?provider=gcp). #### GitHub Three new checks harden GitHub Actions defaults, all contributed by @Edneam. Thank you! * `organization_default_workflow_permissions_read_only` and `repository_default_workflow_permissions_read_only` verify that workflows get a read-only default `GITHUB_TOKEN` at the organization and repository level. * `organization_actions_pull_request_approval_disabled` verifies that organizations prevent GitHub Actions from creating and approving pull requests. Explore all GitHub checks at [Prowler Hub](https://hub.prowler.com/check?provider=github). #### Microsoft 365 * `defender_domain_dmarc_records_published` checks that every Exchange Online domain publishes a DMARC record with an enforcing policy (`p=quarantine` or `p=reject`). Thanks to @Rishi943! Explore all Microsoft 365 checks at [Prowler Hub](https://hub.prowler.com/check?provider=m365). #### Alibaba Cloud * `oss_bucket_versioning_enabled` verifies that OSS buckets keep versioning enabled, allowing recovery from accidental or malicious object overwrite and deletion. Thanks to @abidedavana! * `oss_bucket_server_side_encryption_enabled` verifies that OSS buckets define a default server-side encryption rule, either AES256 or KMS. Thanks to @alexchen-sys! OSS bucket logging, versioning, default encryption, and ACL configurations are also now read correctly from the Alibaba Cloud SDK, so the checks reading them no longer report every bucket as unconfigured. Explore all Alibaba Cloud checks at [Prowler Hub](https://hub.prowler.com/check?provider=alibabacloud). #### Huawei Cloud * `vpc_security_group_open_egress` flags VPC security groups that allow open egress to the internet. Thanks to @tomitobio! Explore all Huawei Cloud checks at [Prowler Hub](https://hub.prowler.com/check?provider=huaweicloud). #### STACKIT * `ske_cluster_no_public_endpoint` flags SKE clusters whose Kubernetes API endpoint is reachable from the whole internet, because the ACL extension is disabled or its allowed CIDR list contains `0.0.0.0/0` or `::/0`. Thanks to @johannes-engler-mw! Explore all STACKIT checks at [Prowler Hub](https://hub.prowler.com/check?provider=stackit). ### 🔐 Security Updates * The API and SDK container images upgrade OpenSSL to 3.5.7-1\~deb13u2, patching ten high CVEs; the UI image upgrades `libcrypto3` and `libssl3` to 3.5.8-r0, patching seven high CVEs; the MCP Server image patches CVE-2026-14456 (OpenSSL), CVE-2026-11822, and CVE-2026-11824 (SQLite). * `sqlparse` upgraded to 0.6.0 in the API, patching CVE-2026-54284, CVE-2026-59893, and CVE-2026-71491. ### 🙌 External Contributors Thank you to our community contributors for this release! * @Edneam: GitHub `organization_default_workflow_permissions_read_only` ([#12122](https://github.com/prowler-cloud/prowler/pull/12122)), `repository_default_workflow_permissions_read_only` ([#12143](https://github.com/prowler-cloud/prowler/pull/12143)), and `organization_actions_pull_request_approval_disabled` ([#12394](https://github.com/prowler-cloud/prowler/pull/12394)) checks * @tamg-aws: four AWS Bedrock checks covering guardrail grounding, CMK encryption, and agent role isolation ([#12459](https://github.com/prowler-cloud/prowler/pull/12459)) * @esquaredsec: AWS `ecr_repository_image_no_secrets` check ([#12123](https://github.com/prowler-cloud/prowler/pull/12123)) * @Rishi943: Microsoft 365 `defender_domain_dmarc_records_published` check ([#11936](https://github.com/prowler-cloud/prowler/pull/11936)) * @abidedavana: Alibaba Cloud `oss_bucket_versioning_enabled` check ([#11913](https://github.com/prowler-cloud/prowler/pull/11913)) * @alexchen-sys: Alibaba Cloud `oss_bucket_server_side_encryption_enabled` check ([#11981](https://github.com/prowler-cloud/prowler/pull/11981)) * @tomitobio: Huawei Cloud `vpc_security_group_open_egress` check ([#12209](https://github.com/prowler-cloud/prowler/pull/12209)) * @johannes-engler-mw: STACKIT `ske_cluster_no_public_endpoint` check ([#11943](https://github.com/prowler-cloud/prowler/pull/11943)) * @gabrielfrdev: cluster name in Kubernetes compliance report outputs ([#12506](https://github.com/prowler-cloud/prowler/pull/12506)) * @jfgmesquita: AWS FSBP compliance mapping fix for IAM.9 and EKS.1 ([#12372](https://github.com/prowler-cloud/prowler/pull/12372)) * @hackertwinten: `ec2_securitygroup_not_used` no longer flags security groups held only by scaled-down AWS Batch compute environments ([#12458](https://github.com/prowler-cloud/prowler/pull/12458)) * @0xTaoZ: ECS task-definition checks no longer report PASS when `DescribeTaskDefinition` fails, shipped early in v5.39.1 ([#12217](https://github.com/prowler-cloud/prowler/pull/12217)) * @ye11oc4t: `ses_identity_not_publicly_accessible` now evaluates every identity authorization policy, shipped early in v5.39.1 ([#12464](https://github.com/prowler-cloud/prowler/pull/12464)) * @Zuhef: IaC provider raises typed exceptions instead of `sys.exit` when cloning the scanned repository or running Trivy fails ([#12227](https://github.com/prowler-cloud/prowler/pull/12227)), Kubernetes kubelet checks no longer disappear from the scan when a `kubelet-config` ConfigMap is broken ([#12225](https://github.com/prowler-cloud/prowler/pull/12225)), and the CLI `--slack` summary is sent for scans with no findings instead of failing with `ZeroDivisionError` ([#12229](https://github.com/prowler-cloud/prowler/pull/12229)) * @m-khan-97: NCSC Cyber Essentials 3.3 compliance framework with Azure provider coverage across the five Cyber Essentials themes ([#11588](https://github.com/prowler-cloud/prowler/pull/11588)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.40.0) for the complete list of changes. **v5.39.0** August 13, 2026 ### 🤖 Lighthouse AI — Finding Skills > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Lighthouse AI now embeds a Skills menu on every finding, answering the questions an analyst actually asks. **Contextual Fix** produces the fix for the finding, **Triage Decision** judges whether it is real and closes it out when it is not, and **Systemic Scope** determines whether the problem is a one-off or everywhere. A free-form "Ask Lighthouse anything" prompt sits in the same menu, and each run shows its progress and offers follow-up actions such as creating a Jira issue or muting the finding. ![Lighthouse AI Skills menu on a finding resource](https://mintcdn.com/prowler/vwGCmVw3_UfFsIeR/images/changelog/v5.39.0-lighthouse-finding-skills.png?fit=max\&auto=format\&n=vwGCmVw3_UfFsIeR\&q=85\&s=625a2f02b9c6ea653487a9477f394146) Read more in the [Lighthouse AI documentation](https://docs.prowler.com/getting-started/products/prowler-cloud-lighthouse). ### ☁️ Azure Management Group Onboarding > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Azure subscriptions no longer onboard one at a time. Choose "Add Multiple Subscriptions With Azure Management Group" in the add-provider wizard, enter the Microsoft Entra tenant ID, and authenticate once with a single tenant-wide service principal: Prowler discovers the entire management-group hierarchy under the tenant root, lets you select the subscriptions to onboard, and creates their providers with the management-group structure preserved. Azure now matches the one-step onboarding that AWS Organizations and GCP organizations already have. ![Azure onboarding method selector with the Management Group option](https://mintcdn.com/prowler/vwGCmVw3_UfFsIeR/images/changelog/v5.39.0-azure-mg-selector.png?fit=max\&auto=format\&n=vwGCmVw3_UfFsIeR\&q=85\&s=f576156c3e2e6e666de7ec5e7f219963) Read more in the [Azure Management Groups documentation](https://docs.prowler.com/user-guide/tutorials/prowler-cloud-azure-management-groups). ### ✅ Findings Triage — Verify MANUAL Findings as PASS > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Checks that require human judgment report `MANUAL` findings. For these findings, and only for them, the triage status selector now offers **Resolved**: choosing it asks for the required written evidence and verifies the finding as passing. The finding then reports an effective `PASS` while preserving the raw `MANUAL` scan result, across findings, finding groups, compliance reports, and scans, with the attestation's author, evidence, and validity always visible. Attestations expire automatically after 90 days, or as soon as a new scan reports a real failure, returning the finding to the review queue. ![Triage status selector offering Resolved on a MANUAL finding](https://mintcdn.com/prowler/vwGCmVw3_UfFsIeR/images/changelog/v5.39.0-manual-pass-selector.png?fit=max\&auto=format\&n=vwGCmVw3_UfFsIeR\&q=85\&s=7f240b825f8e9edc420120905a2c795d) ![Manual Pass details showing evidence, author, and validity](https://mintcdn.com/prowler/vwGCmVw3_UfFsIeR/images/changelog/v5.39.0-manual-pass-details.png?fit=max\&auto=format\&n=vwGCmVw3_UfFsIeR\&q=85\&s=e36194e4bea73eb092a41f6cec7fb750) Read more in the [Findings Triage documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-findings-triage#verify-a-manual-finding-as-pass). ### ☁️ Prowler Cloud MCP — Organizations Management and Grouped Jira Dispatch > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). The hosted Prowler Cloud MCP server adds eight organization tools, so an agent can onboard and manage entire cloud organizations end to end: create the organization, discover its accounts, subscriptions, and projects, apply the selection, and manage the resulting providers. The tools cover AWS Organizations, GCP organizations, and Azure tenant root management groups, and they are available to Lighthouse AI. `prowler_send_findings_to_jira` also gains Cloud-only dispatch capabilities: select failed findings by check IDs against the latest completed scan, and send them in grouped mode, one Jira work item per check listing up to 50 affected resources, with per-group error reporting. Read more in the [Prowler MCP tools documentation](https://docs.prowler.com/getting-started/basic-usage/prowler-mcp-tools) and its [Jira operations reference](https://docs.prowler.com/getting-started/basic-usage/prowler-mcp-tools#jira-operations). ### 🕸️ Attack Paths — Grouped Graph with Outcome Destinations > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). The Attack Paths graph now reads from source to destination. Resources of the same class collapse into a single expandable node with a count, clicking reveals its members, and every path terminates in an explicit outcome node naming the destination impact: code execution, privilege escalation, public exposure, or resource inventory. The per-account hub node is gone, and the clicked resource stays highlighted while its findings are expanded. ![Attack Paths graph from the Internet to a public exposure outcome node](https://mintcdn.com/prowler/vwGCmVw3_UfFsIeR/images/changelog/v5.39.0-attack-paths-graph.png?fit=max\&auto=format\&n=vwGCmVw3_UfFsIeR\&q=85\&s=c71b368264c3af3d168faf559830117e) Explore the full Attack Paths query catalog at [Prowler Hub](https://hub.prowler.com/attack-paths). Read more in the [Attack Paths documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-attack-paths). ### 📚 New Compliance Framework — CMMC 2.0 The Cybersecurity Maturity Model Certification (CMMC) is the certification the US Department of Defense requires from contractors and suppliers that handle federal contract data. Prowler now includes CMMC 2.0 as a universal framework with all 149 requirements defined by the CMMC Program rule (32 CFR Part 170), organized in its three levels: * **Level 1 (Foundational):** 15 requirements for the basic safeguarding of Federal Contract Information, from FAR 52.204-21. * **Level 2 (Advanced):** 110 requirements from NIST SP 800-171 Rev 2, protecting Controlled Unclassified Information. * **Level 3 (Expert):** 24 enhanced requirements from NIST SP 800-172 for the most sensitive programs. Requirements map to Prowler checks across AWS, Azure, GCP, Alibaba Cloud, Oracle Cloud, and Microsoft 365, so one framework reports the compliance posture of the whole estate. Read more in the [Compliance documentation](https://docs.prowler.com/user-guide/compliance/tutorials/compliance). ### 🔍 Checks #### Microsoft 365 Twenty new Entra ID checks expand the coverage of CIS Microsoft 365 Foundations Benchmark v7.0.0: * **Password protection:** custom banned password list, on-premises enforcement, and lockout threshold and duration. * **Default user permissions:** security group and Microsoft 365 group creation restricted, and guest invitations limited to allowed domains. * **Conditional Access:** high and medium sign-in risk blocked, authentication transfer blocked, untrusted locations blocked, trusted named locations defined, sign-in frequency enforced, and token protection enforced. * **Sessions and authentication methods:** idle session timeout configured, email one-time passcodes disabled, and Microsoft Authenticator context shown. * **PIM and access reviews:** approval required to activate the Global Administrator and Privileged Role Administrator roles, and access reviews configured for guest users and privileged roles. Explore all Microsoft 365 checks at [Prowler Hub](https://hub.prowler.com/check?provider=m365). #### AWS Two new checks detect hardcoded secrets: * `batch_job_definition_no_secrets` scans Batch job definition environment variables and command parameters. Thanks to @praneetrajv! * `awslambda_layer_no_secrets_in_content` scans Lambda layer package content. Thanks to @ganiganesh25! Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). ### 🙌 External Contributors Thank you to our community contributors for this release! * @praneetrajv: AWS `batch_job_definition_no_secrets` check ([#12117](https://github.com/prowler-cloud/prowler/pull/12117)) * @ganiganesh25: AWS `awslambda_layer_no_secrets_in_content` check ([#12233](https://github.com/prowler-cloud/prowler/pull/12233)) * @andoniaf: GitHub `organization_repository_creation_limited` now reports low severity when repository creation is limited to private or internal visibility ([#12164](https://github.com/prowler-cloud/prowler/pull/12164)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.39.0) for the complete list of changes. **v5.38.0** August 6, 2026 ### 📌 Compliance Watchlist > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Compliance Watchlist keeps the frameworks an organization tracks in one shared list. Pin frameworks from any compliance view, manage several at once through a searchable catalog, and filter the Compliance section to show only the pinned frameworks. The Overview page now reports the latest score for every pinned framework, while finding details highlight the watched frameworks associated with each check. Universal frameworks remain a single watchlist entry across provider views, keeping the organization's priorities consistent everywhere. ![Compliance Watchlist editor](https://mintcdn.com/prowler/hxdg66D95nJJyk4c/images/compliance/prowler-app-compliance-watchlist-editor.png?fit=max\&auto=format\&n=hxdg66D95nJJyk4c\&q=85\&s=35c5da10879ca3735bd5e7ba792dda38) Read more in the [Compliance Watchlist documentation](https://docs.prowler.com/user-guide/compliance/tutorials/compliance#tracking-frameworks-with-the-compliance-watchlist). ### 🔐 SAML SSO - Multiple Email Domains > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). One SAML configuration can now authorize a primary email domain and up to 19 additional domains through the same Identity Provider. Every domain shares one stable Assertion Consumer Service (ACS) URL based on the primary domain, so subsidiaries, acquired companies, regional domains, and multiple brands no longer require separate tenants or duplicated SAML applications. Domain ownership remains tenant-bound throughout the authentication flow. During service provider-initiated sign-in, the discovery domain and the domain asserted by the Identity Provider must resolve to the same tenant before provisioning continues. ![SAML configuration with multiple email domains](https://mintcdn.com/prowler/f0E1vuwpc9jDrssD/images/prowler-app/saml/saml-multiple-domains.png?fit=max\&auto=format\&n=f0E1vuwpc9jDrssD\&q=85\&s=cd29e76ff3f4dd10480f3261e0c822de) Read more in the [SAML SSO documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-sso#add-multiple-saml-domains). ### 👥 User Sign-In Methods > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). The Users table now shows each account's sign-in methods as tags, including email/password, Google, GitHub, SAML with linked domains, and Partner SSO. Accounts without a reported method display a placeholder. ![Users table showing sign-in method tags](https://mintcdn.com/prowler/qg-iyeXcEinAYDC0/images/changelog/v5.38.0-user-sign-in-methods.png?fit=max\&auto=format\&n=qg-iyeXcEinAYDC0\&q=85\&s=e7958e573c6cf37a365bd26b0197e5c2) ### 🕸️ Attack Paths - Expanded AWS Privilege-Escalation Coverage Attack Paths adds 20 AWS privilege-escalation queries from [pathfinding.cloud](https://pathfinding.cloud), while `iam_policy_allows_privilege_escalation` gains 22 additional escalation combinations. The new coverage includes service `iam:PassRole` paths across AWS Batch, Braket, Cognito Identity, ECS, EMR, EMR Serverless, GameLift, Glue, EC2 Image Builder, Kinesis Analytics, HealthOmics, EventBridge Scheduler, Systems Manager, and Step Functions. It also covers existing-resource abuse, permissions-boundary removal, role assumption, and IAM Identity Center permission-set policy injection. The query catalog now exposes each AWS query's outcome category, distinguishing code execution, privilege escalation, public exposure, and resource inventory. Explore the full Attack Paths query catalog at [Prowler Hub](https://hub.prowler.com/attack-paths). Read more in the [Attack Paths documentation](https://docs.prowler.com/user-guide/tutorials/prowler-app-attack-paths). ### 🔍 Checks #### Microsoft 365 Twelve new checks expand the coverage of CIS Microsoft 365 Foundations Benchmark v7.0.0: * **Admin Center:** Shared Bookings is disabled. * **Defender:** Priority account protection and strict preset security policies are enabled. * **Entra ID:** Six checks cover device registration restrictions, local administrator behavior, device limits, LAPS, and BitLocker key visibility. * **Exchange Online:** Personal accounts in Outlook on the web are disabled and Direct Send is rejected. * **Microsoft Teams:** External access from trial-only tenants is blocked. Explore all Microsoft 365 checks at [Prowler Hub](https://hub.prowler.com/check?provider=m365). ### 🔐 Security * Prowler API, UI, SDK, and MCP container images now publish per-architecture Software Bills of Materials (SBOMs) and build-provenance attestations. Prowler Cloud production and Prowler Private Cloud images carry the same attestations. * SDK and API container builds verify the checksums of downloaded PowerShell, Trivy, and zizmor binaries before installation. * Grype now complements Trivy across the container-image security gates, detecting components and vulnerabilities that manifest-based scanners can miss and blocking fixable high and critical findings. * `aiohttp` was upgraded to 3.14.3 to address CVE-2026-69244. `cryptography` was upgraded to 50.0.0 to address CVE-2026-69247 and CVE-2026-69249. See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.38.0) for the complete list of changes. **v5.37.0** August 3, 2026 ### 💬 Lighthouse AI — Context-Aware Chat and a Bigger Toolbox > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Lighthouse AI is now aware of your working context when in Prowler Cloud. Messages carry page-aware context — the page you are on, the finding or resource open in the side panel, and its metadata — so "explain this" just works, and each page offers concise contextual suggestions to start from. ![Lighthouse AI answering "explain this finding" from the side panel, with the page context chip highlighted in the composer](https://mintcdn.com/prowler/y2Qml-1Q66KeL6CI/images/prowler-app/lighthouse/prowler-cloud/side-panel-context-aware.png?fit=max\&auto=format\&n=y2Qml-1Q66KeL6CI\&q=85\&s=ccf008d9a523c9585bc303a4f8465794) Lighthouse also gained access to every tool family the Prowler MCP server advertises: scan configurations, scan scheduling, finding triage, alert rules and recipients, integrations, users, and roles. Every action remains gated by RBAC: Lighthouse AI can only do what the user asking could do themselves. Read more in the [Lighthouse AI documentation](/getting-started/products/prowler-cloud-lighthouse). ### 🔌 Prowler MCP — Integrations, Users, and Roles Prowler MCP gained three tool families, available on both the Cloud and the self-hosted Local MCP Server: * **[Integrations](/getting-started/basic-usage/prowler-mcp-tools#integrations-management)** — manage where Prowler sends its results, with the full lifecycle for Amazon S3, AWS Security Hub, and Jira: create them, update credentials, configuration and attached providers, re-check connections, and delete them — plus turning findings into Jira work items directly from a conversation. * **[Users](/getting-started/basic-usage/prowler-mcp-tools#user-management)** — read-only tools to list the tenant users with their emails and identify the authenticated user. * **[Roles](/getting-started/basic-usage/prowler-mcp-tools#role-management)** — browse the RBAC roles defined in the tenant, inspect the capabilities each one grants, and set the role a user holds. ### ☁️ Prowler MCP — Cloud-Only Tools > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). These tools are exposed only by the Cloud MCP Server at `https://mcp.prowler.com/mcp`; the self-hosted Local MCP Server **does not** include them. A new `prowler_cloud_*` namespace adds 32 tools so your AI assistant can run Prowler Cloud workflows end to end instead of only reading from them: * **[Alerts](/getting-started/basic-usage/prowler-mcp-tools#alerts)** — create and manage alert rules and email recipients, and browse the fired-alert history. Rule conditions can be dry-run before saving, so you can see what a rule would match without persisting anything. * **[Findings Triage](/getting-started/basic-usage/prowler-mcp-tools#findings-triage)** — set a finding's triage status and attach notes documenting the decision. Unlike muting, the finding stays visible. * **[Scan Scheduling](/getting-started/basic-usage/prowler-mcp-tools#scan-scheduling)** — configure daily, interval, weekly, or monthly recurring scans, one provider at a time or applied across many at once. * **[Scan Configurations](/getting-started/basic-usage/prowler-mcp-tools#scan-configurations)** — build reusable check and compliance selections and attach them to providers. Read more in the [Prowler MCP tools reference](/getting-started/basic-usage/prowler-mcp-tools#prowler-cloud-tools). ### 🧭 Compliance — Grouped by provider of the same type > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). One framework, every provider, a single answer. Building on the cross-provider-type roll-up, the Compliance section now groups compliance for all providers of the same type: a **single-provider framework** — CIS AWS, CIS GCP, ENS for Azure — is aggregated across the latest completed scan of every provider of that type. Each framework card rolls up into a consolidated posture with a per-provider breakdown, a findings drill-down, and a combined executive PDF report. Requirement status follows the same strict precedence (FAIL over PASS over MANUAL), so one failing provider flags the requirement for the whole estate. ![Across providers compliance section](https://mintcdn.com/prowler/y2Qml-1Q66KeL6CI/images/compliance/prowler-app-across-providers-expanded.png?fit=max\&auto=format\&n=y2Qml-1Q66KeL6CI\&q=85\&s=0cece100375e4d192af0a0e736fff533) The Compliance tabs were also renamed to say what they aggregate: "Per Scan" is now **Single Scan**, "Cross-Provider" is now **Multiple Scans**, and Compliance lands on Multiple Scans by default. ![Cross-provider compliance detail across providers](https://mintcdn.com/prowler/y2Qml-1Q66KeL6CI/images/compliance/prowler-app-across-providers-detail.png?fit=max\&auto=format\&n=y2Qml-1Q66KeL6CI\&q=85\&s=cb3f17d7b0b131e8d19670972f8f60b4) Read more in the [Cross-Provider Compliance documentation](/user-guide/compliance/tutorials/cross-provider-compliance). ### ☁️ GCP Organization Onboarding > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Onboarding an entire Google Cloud organization is now a single guided flow. Provide an organization-level credential and Prowler discovers the full hierarchy, every folder and project. Pick the folders and projects to onboard from a selection tree, set custom aliases, test the connection, and launch: each selected project is registered as a provider, with no need to add them one by one. Post-onboarding management is covered too, including credential replacement and organization-wide deletion. Read more in the [GCP Organizations documentation](/user-guide/tutorials/prowler-cloud-gcp-organizations). ### 🕸️ Attack Paths — More Privilege Escalation Queries Attack Paths adds four AWS privilege-escalation detection queries from [pathfinding.cloud](https://pathfinding.cloud). Thanks to @paramanandmallik! * **[STS-002](https://hub.prowler.com/attack-paths/aws-sts-privesc-cross-account-trust)** — cross-account role trust * **[STS-003](https://hub.prowler.com/attack-paths/aws-sts-privesc-wildcard-trust)** — wildcard role trust * **[IAM-022](https://hub.prowler.com/attack-paths/aws-iam-privesc-delete-user-permissions-boundary)** — user permissions-boundary removal * **[SSO-001](https://hub.prowler.com/attack-paths/aws-sso-privesc-permission-set-escalation)** — IAM Identity Center permission-set escalation The query info panel now links every query to its page on [Prowler Hub](https://hub.prowler.com), and the IAM privilege-escalation queries were reworked to run efficiently on accounts with many IAM roles, users, or groups, fixing runtime errors and timeouts on large graphs. Read more in the [Attack Paths documentation](/user-guide/tutorials/prowler-app-attack-paths). ### 🛡️ AWS Confidential Computing — Nitro Enclaves Checks Prowler adds the first CSPM coverage for confidential computing workloads on AWS, with **11 new checks** for [Nitro Enclaves](https://aws.amazon.com/ec2/nitro/nitro-enclaves/), developed together with [Guillermo Ruiz](https://www.linkedin.com/in/gruizesteban/) from AWS. * **Workload host environment (EC2)** — five `ec2_confidential_workload_host_*` checks for the parent instance: IMDSv2 not enforced, public IP exposure, unrestricted ingress, exposed vsock proxy ports, and hosts not running. * **KMS attestation policy** — six `kms_key_enclave_*` checks for the key policies gating enclave secrets: attestation not enforced or bypassable, missing deployment binding, debug-mode attestations, PCR mismatches, and unknown enclave images. All checks are fully passive, using AWS APIs and CloudTrail with no instance access or SSM agent required, and are mapped across 23 compliance frameworks, including NIST 800-53 Rev 5, PCI-DSS v4.0, ISO 27001:2022, SOC 2, HIPAA, and MITRE ATT\&CK. Read more about it in this [blog post](https://prowler.com/blog/your-llm-runs-in-a-nitro-enclave-who-is-checking-the-enclave). Try them out now at [cloud.prowler.com](https://cloud.prowler.com/sign-up)! ### 🏢 New Provider — Huawei Cloud Prowler now scans [**Huawei Cloud**](https://www.huaweicloud.com/), with **25 checks** across ten services: CTS, ECS, ELB, EVS, IAM, KMS, OBS, RDS, VPC, and WAF, plus the CIS Huawei Cloud Foundations Benchmark 1.0 compliance framework. Thanks to @tomitobio for their 1st provider in Prowler! To scan a Huawei Cloud account, export the IAM user's access key credentials and run Prowler CLI: ```bash theme={null} export HUAWEICLOUD_ACCESS_KEY_ID="your-access-key-id" export HUAWEICLOUD_SECRET_ACCESS_KEY="your-secret-access-key" prowler huaweicloud ``` Read more in the [Huawei Cloud documentation](/user-guide/providers/huaweicloud/getting-started-huaweicloud). Explore all Huawei Cloud checks at [Prowler Hub](https://hub.prowler.com/check?provider=huaweicloud). ### 🔍 Checks #### AWS * `codecommit_repository_no_secrets`, alongside the new `codecommit` service, scans files tracked at the tip of each repository's default branch for hardcoded secrets. Thanks to @Sid-0602! * `glue_catalog_connection_no_secrets` detects secrets in Glue Data Catalog connection properties. Thanks to @l46983284-cpu, @Rishi943, and @UTKARSH698! * `ec2_instance_stopped_older_than_specific_days` detects EC2 instances stopped longer than a configurable number of days (default 30). Thanks to @Nithin078! * `sagemaker_endpoint_config_kms_encryption_enabled` verifies SageMaker endpoint configurations use a KMS key for storage volume encryption. Thanks to @Nithin078 and @l46983284-cpu! Read more in the [AWS documentation](/user-guide/providers/aws/getting-started-aws). Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). ### 📤 OCSF Output — MITRE ATT\&CK Enrichment OCSF detection finding output now populates `finding_info.analytic` with the Prowler check rule and `finding_info.attacks` with MITRE ATT\&CK technique and tactic objects for findings with MITRE ATT\&CK compliance metadata. Thanks to @AlexanderSanin! ### 🐞 Fixed * AWS Security Hub integrations now persist successful recovery checks during finding delivery, keeping connection status and the last-checked time accurate. * Social sign-up now creates authentication, tenant, and membership records in a single transaction, fully rolling back failed provisioning to prevent incomplete accounts. * The SAML configuration form keeps the ACS URL field stable while generating the callback URL and exposes the copy action only after a valid URL is available. * SAML users without a `userType` attribute and without an existing role now receive a least-privilege `read_only` fallback role, so role-dependent operations continue to work without granting management permissions. ### 🔐 Security * Provider deletion, connection checks, scan creation, provider secrets, provider groups, and daily schedules now respect role provider-group visibility. * HTML reports escape provider-originated finding fields, preventing stored cross-site scripting through malicious cloud resource tags. [https://github.com/prowler-cloud/prowler/security/advisories/GHSA-c2jg-2778-ggm4](https://github.com/prowler-cloud/prowler/security/advisories/GHSA-c2jg-2778-ggm4) * Authentication with an API key whose owning user was deleted now returns `401`, and user deletion revokes the user's API keys across all their tenants. ### 🙌 External Contributors Thank you to our community contributors for this release! * @tomitobio: Huawei Cloud provider with CIS 1.0 benchmark ([#11950](https://github.com/prowler-cloud/prowler/pull/11950)) * @paramanandmallik: four AWS privilege-escalation Attack Paths queries ([#11460](https://github.com/prowler-cloud/prowler/pull/11460)) * @Sid-0602: AWS `codecommit` service and `codecommit_repository_no_secrets` check ([#11846](https://github.com/prowler-cloud/prowler/pull/11846)) * @l46983284-cpu, @Rishi943, and @UTKARSH698: AWS `glue_catalog_connection_no_secrets` check ([#11963](https://github.com/prowler-cloud/prowler/pull/11963)) * @Nithin078: AWS `ec2_instance_stopped_older_than_specific_days` ([#12076](https://github.com/prowler-cloud/prowler/pull/12076)) and `sagemaker_endpoint_config_kms_encryption_enabled` ([#12118](https://github.com/prowler-cloud/prowler/pull/12118), co-authored with @l46983284-cpu) checks * @AlexanderSanin: MITRE ATT\&CK enrichment in OCSF detection finding output ([#11492](https://github.com/prowler-cloud/prowler/pull/11492)) * @stefanobaldo: GCP gen2 Cloud Functions IAM policy retrieval is now thread-safe ([#12107](https://github.com/prowler-cloud/prowler/pull/12107)) * @rayair250-droid: GCP SSH and RDP firewall checks now detect exposed ports in any position within multi-port rules ([#12115](https://github.com/prowler-cloud/prowler/pull/12115)) * @jbchief-dev: secret ignore patterns now use Kingfisher-compatible LF line indexing ([#12141](https://github.com/prowler-cloud/prowler/pull/12141)) * @bmbferreira: Helm chart improvements — immutable chart versions on release ([#12056](https://github.com/prowler-cloud/prowler/pull/12056)) and capped Celery worker concurrency ([#12054](https://github.com/prowler-cloud/prowler/pull/12054)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.37.0) for the complete list of changes. **v5.36.0** July 24, 2026 ### 🎫 Finding Groups - Jira > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Selected Findings, Finding Groups, and mixed selections can now be sent to Jira. When you select multiple findings, choose between one grouped issue or separate issues. Generated issues keep their Prowler context with deep links and filter details, while the UI provides clear dispatch and failure feedback. ![Send findings to Jira](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.36.0-finding-groups-jira.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=1867841e3326cf8d449c8cd90de51c1b) Read more in the [Jira integration documentation](/user-guide/tutorials/prowler-app-jira-integration). ### 🕸️ Attack Paths - Queries > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Prowler Cloud now records which built-in Attack Paths queries returned data at the end of each scan. The query selector hides confirmed-empty queries for the selected scan, so you can focus on paths that exist without opening blank graph views. Errored, unknown, and parameterized queries remain available when they still require investigation or input. All Attack Paths queries are now published on [Prowler Hub](https://hub.prowler.com), where you can browse the full catalog. ![Attack Paths query selector](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.36.0-attack-paths-queries.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=7828819a31c8c3c69905032d6df0ebdf) Read more in the [Attack Paths documentation](/user-guide/tutorials/prowler-app-attack-paths). ### 🧑‍🏫 New Tutorials: Connect Your AI Agents to Prowler Cloud > [!NOTE] > > This feature needs a Prowler Cloud API key, so it is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). New tutorials walk you through connecting your own AI agents to Prowler Cloud, so they can query your security posture and act on it programmatically. Read more in the [AI agents documentation](/user-guide/ai-agents/index). ### ☁️ Region-less Oracle Cloud Infrastructure Setup Oracle Cloud Infrastructure (OCI) provider credentials no longer require a region. Existing clients can still send the legacy `region` field for compatibility, but the API ignores it before storing credentials or starting a scan. This removes an unnecessary step from OCI onboarding. Read more in the [OCI documentation](/user-guide/providers/oci/getting-started-oci). ### 🔍 Checks #### AWS * `sagemaker_notebook_instance_no_secrets` scans the `OnCreate` and `OnStart` lifecycle scripts of SageMaker notebook instances for hardcoded API keys, passwords, tokens, connection strings, and other secrets. Thanks to @kiranrajsg! Read more in the [AWS documentation](/user-guide/providers/aws/getting-started-aws). Explore all AWS checks at [Prowler Hub](https://hub.prowler.com/check?provider=aws). ### 🔐 Security * Integration responses and operations now respect provider visibility, preventing hidden-provider disclosure and blocking unauthorized attachment, connection checks, Jira dispatches, edits, and deletion. * Next.js was updated from 16.2.9 to 16.2.11, patching four high-severity and five medium-severity vulnerabilities. * The unused `npm` CLI was removed from the UI container image, eliminating the bundled `node-tar` CVE-2026-59873 and reducing exposure to future bundled npm vulnerabilities. * Vitest and its browser packages were updated from 4.1.8 to 4.1.10, resolving the critical `@vitest/browser` file-access permission bypass. These are development dependencies and have no runtime impact. * Kubernetes kubeconfig validation now blocks legacy `auth-provider.config.cmd-path` command authentication, closing a command-execution bypass. * `next-auth` was updated from 5.0.0-beta.30 to 5.0.0-beta.32, patching two critical Auth.js advisories: existence-based authorization checks that could fail open when a provider is misconfigured, and a homoglyph `@` bypass in email address normalization. The bump also pulls in the patched `@auth/core` 0.41.3 transitively. ### 🙌 External Contributors Thank you to our community contributors for this release! * @kiranrajsg: AWS `sagemaker_notebook_instance_no_secrets` check ([#11843](https://github.com/prowler-cloud/prowler/pull/11843)) * @owenchenxy: Alibaba Cloud SSH and RDP security group checks now handle capitalized `Policy="Accept"` values correctly ([#12049](https://github.com/prowler-cloud/prowler/pull/12049)) * @rsaladra: S3 bucket name validation no longer raises an invalid escape sequence `SyntaxWarning` at startup ([#12041](https://github.com/prowler-cloud/prowler/pull/12041)) * @SujayKulkarni-2211: Updated the AWS check count in the README ([#12011](https://github.com/prowler-cloud/prowler/pull/12011)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.36.0) for the complete list of changes. **v5.35.0** July 17, 2026 ### 💬 Lighthouse AI - Side Chat > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Lighthouse AI now lives in a side panel you can open from anywhere in the app. Ask about the findings you are looking at without leaving the page, and expand to the full-page chat at any time: your draft, messages, and streaming response come along. Finding and resource details share the same panel, with tabs to switch between Details and Lighthouse AI. ![Lighthouse AI side chat](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.35.0-lighthouse-ai-side-chat.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=59996bc4df1af48d70568dc084443a99) Read more in the [Lighthouse AI documentation](/getting-started/products/prowler-cloud-lighthouse#side-panel). ### 🤖 Lighthouse AI - Take Action > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Lighthouse AI is no longer read-only. Ask it to do things and it will: connect or remove providers, trigger a scan, schedule daily scans, update scan settings, and manage your mutelist and mute rules, straight from the chat. Every action is gated by RBAC: Lighthouse can only do what the user asking could do themselves. Read more in the [Lighthouse AI capabilities](/getting-started/products/prowler-cloud-lighthouse#capabilities). ### ☁️ One-step AWS Organizations onboarding > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Onboarding an entire AWS Organization is now a single step. One CloudFormation quick-create link deploys the management account role and a service-managed StackSet that rolls the role out to every member account, replacing the manual StackSet console setup. Target the whole organization or a specific Organizational Unit or Root ID, and deploy from the management account or a delegated administrator. The S3 integration quick-create link also pre-fills the bucket owner account ID, preventing a stack validation error. ![AWS Organizations onboarding wizard](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.35.0-aws-orgs-wizard.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=1eadc27280932623270ccc20b47e00c6) Built on the full-organization CloudFormation template contributed by @jchrisfarris — thanks! Read more in the [AWS Organizations documentation](/user-guide/tutorials/prowler-cloud-aws-organizations). ### 🎯 Scan configurations: exclude checks and services > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Scan configurations now accept `excluded_checks` and `excluded_services` to narrow the execution scope. Skip individual checks or entire services per provider, and the scan does not run them at all: less noise, faster scans, and no findings you would mute anyway. Read more in the [Scan Configuration documentation](/user-guide/tutorials/prowler-app-scan-configuration#limiting-the-scan-scope). ### 🧭 Redesigned sidebar navigation The sidebar was redesigned around how you actually work: grouped sections for security, settings, and help, a Home/Chat switch at the top, collapsible configuration entries, clearer active states, and a responsive mobile overlay. ![Redesigned sidebar](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.35.0-new-menu.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=cc32f0b2cf803c1bfbf6f782b14765cb) ### 🔌 Prowler MCP tools renamed to `prowler_*` Core Prowler tools in Prowler MCP moved from the `prowler_app_*` prefix to the shorter `prowler_*` namespace, and the MCP documentation was restructured around it. Legacy `prowler_app_*` names keep working in Lighthouse AI, so existing setups are not broken. Read more in the [Prowler MCP tools reference](/getting-started/basic-usage/prowler-mcp-tools). ### 🔐 Security * Jira integration credentials now only accept bare Atlassian site names (letters, numbers, and hyphens), and Jira tenant information requests validate site names and no longer follow redirects. * Social account linking now requires a verified matching email from both the identity provider and the existing user account, and account connection notification emails are disabled. * 13 advisories reported by `pnpm audit` on the UI (3 high, 9 moderate, 1 low) are resolved with patched versions of `hono`, `ws`, `vite`, `dompurify`, `js-yaml`, `@opentelemetry/core`, and `@babel/core`, including `hono` CVE-2026-59896. ### 🙌 External Contributors No external contributors in this release. Special mention to @jchrisfarris, whose full-organization CloudFormation template from v5.34.0 powers the new one-step AWS Organizations onboarding ([#10403](https://github.com/prowler-cloud/prowler/pull/10403)). See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.35.0) for the complete list of changes. **v5.34.0** July 15, 2026 ### 🏷️ New product names The Prowler family has grown, and the names now say what each product is. Same products, clearer names: **Prowler products:** * **Prowler Cloud** — the managed cloud security platform operated by the Prowler team. * **Prowler Private Cloud** (formerly *Prowler Enterprise*) — the self-hosted deployment of Prowler Cloud in your own environment. * **Prowler Hub** — the free public library of versioned checks, cloud service artifacts, and compliance frameworks. * **Prowler Lighthouse AI** — The Agentic Cloud Defender in Prowler Cloud and Prowler Private Cloud. * **Prowler MCP** — the MCP server that connects AI assistants and agents to Prowler, including the IDE plugins. **Open source projects:** * **Prowler CLI** — the command-line scanner for all supported providers. * **Prowler Local Server** (formerly *Prowler App*) — the self-hosted web application and API to run scans, visualize findings, and manage providers. * **Prowler Local Dashboard** — the web dashboard for visualizing Prowler CLI scan results, distributed with the CLI. * **Prowler SDK** — the Python library behind Prowler CLI and Prowler Local Server. See the full family in the [Prowler products documentation](/getting-started/products). ### 🧭 Cross-Provider Compliance > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). One framework, every cloud, a single answer. The new **Cross-provider** tab in Compliance takes the most recent completed scan of every compatible provider and rolls them up into a single compliance posture per framework, with a per-provider breakdown and a combined executive PDF report. Requirement status follows strict precedence (FAIL over PASS over MANUAL), so one failing provider is enough to flag a requirement across your whole estate. ![Cross-provider compliance overview](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.34.0-cross-provider-compliance-overview.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=7c84bc9c88f4e379ed15ecb2d4a09dce) Three universal frameworks support it today: * **CIS Controls 8.1** — AWS, Azure, Google Cloud, Microsoft 365, Kubernetes, GitHub, Google Workspace, Okta, Oracle Cloud, Alibaba Cloud, Cloudflare, MongoDB Atlas, OpenStack, and Vercel. * **CSA CCM 4.0** — AWS, Azure, Google Cloud, Alibaba Cloud, and Oracle Cloud. * **DORA 2022/2554** — AWS, Azure, Google Cloud, Alibaba Cloud, and Cloudflare. Filter by provider type, account, or provider group, drill into each framework's requirements, and export the combined PDF. ![Cross-provider compliance detail](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.34.0-cross-provider-compliance-detail.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=79d26f35a19cc2f0c5297317d9b4aebb) Read more in the [Cross-Provider Compliance documentation](/user-guide/compliance/tutorials/cross-provider-compliance). ### 🏢 New Provider — E2E Networks Prowler now scans [**E2E Networks**](https://www.e2enetworks.com/), with **27 checks** spanning compute nodes, networking, security groups, load balancers, block and file storage, and managed databases. Thanks to @deepak7093 for their 1st provider in Prowler! Available in the Prowler CLI: ```bash theme={null} export E2E_NETWORKS_API_KEY="your-api-key" export E2E_NETWORKS_AUTH_TOKEN="your-auth-token" export E2E_NETWORKS_PROJECT_ID="your-project-id" prowler e2enetworks ``` Read more in the [E2E Networks documentation](/user-guide/providers/e2enetworks/getting-started-e2enetworks). Explore all E2E Networks checks at [Prowler Hub](https://hub.prowler.com/check?provider=e2enetworks). ### 🔐 Security User role relationship updates in the API are now limited to the active tenant, preserving the role assignments the same user holds in other tenants. ### 🔍 Checks #### AWS * `ec2_ami_account_block_public_access` — verifies AMI block public access is enabled at the account level in each Region, so AMIs cannot be shared publicly. Thanks to @goutham-hari! * `datapipeline_pipeline_no_secrets_in_definition` — scans Data Pipeline object fields, parameter objects, and parameter values for hardcoded secrets with Kingfisher. Thanks to @YinkaMetrics! * `elbv2_listener_pqc_tls_enabled` — verifies ELBv2 HTTPS/TLS listeners use post-quantum TLS security policies with TLS 1.2 or higher, helping reduce harvest-now-decrypt-later exposure. * `amplify_app_no_secrets_in_environment` — scans Amplify app and branch environment variables and build settings (buildSpec) for hardcoded secrets with Kingfisher. Thanks to @Deep070203! #### Azure * `app_function_ensure_http_is_redirected_to_https` — verifies that Function Apps enforce HTTPS-only traffic. Thanks to @amandalal007! #### Kubernetes * `core_minimize_hostpath_volume_mounts` — detects Pods that use `hostPath` volumes. Thanks to @0xTaoZ! * `core_readonly_root_filesystem_enabled` — verifies that every container in each Pod explicitly sets `readOnlyRootFilesystem: true` in its security context. Thanks to @Weedle02! #### STACKIT * `iaas_server_public_ip_attached` — flags IaaS servers that have a public IP address directly attached to a network interface. Thanks to @johannes-engler-mw! Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### 🙌 External Contributors Thank you to our community contributors for this release! * @jchrisfarris — Deploy AWS Organizations with the CloudFormation template in one step ([#10403](https://github.com/prowler-cloud/prowler/pull/10403)) * @deepak7093 — New E2E Networks provider: 27 checks across compute nodes, networking, security groups, load balancers, block/file storage, and managed databases ([#11654](https://github.com/prowler-cloud/prowler/pull/11654)) * @goutham-hari — AWS `ec2_ami_account_block_public_access` check ([#11828](https://github.com/prowler-cloud/prowler/pull/11828)) * @YinkaMetrics — AWS `datapipeline_pipeline_no_secrets_in_definition` check ([#11821](https://github.com/prowler-cloud/prowler/pull/11821)) * @amandalal007 — Azure `app_function_ensure_http_is_redirected_to_https` check ([#11929](https://github.com/prowler-cloud/prowler/pull/11929)) * @0xTaoZ — Kubernetes `core_minimize_hostpath_volume_mounts` check ([#11837](https://github.com/prowler-cloud/prowler/pull/11837)) * @Weedle02 — Kubernetes `core_readonly_root_filesystem_enabled` check ([#11835](https://github.com/prowler-cloud/prowler/pull/11835)) * @johannes-engler-mw — STACKIT `iaas_server_public_ip_attached` check ([#11549](https://github.com/prowler-cloud/prowler/pull/11549)) * @janderik — Trailing newlines added to compliance, region, and fixture data files for POSIX compliance ([#11765](https://github.com/prowler-cloud/prowler/pull/11765)) * @Deep070203 — AWS `amplify_app_no_secrets_in_environment` check ([#11825](https://github.com/prowler-cloud/prowler/pull/11825)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.34.0) for the complete list of changes. **v5.33.0** July 7, 2026 ### 🤖 Lighthouse AI — The Agentic Cloud Defender > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Lighthouse AI is now a full agentic assistant wired to the Prowler Cloud backend. Ask it about your findings, your compliance posture, or your riskiest resources, and watch it work: the agent discovers and runs the Prowler tools it needs to answer, with every tool call visible in the new agentic view. It reads your security data through read-only tools, so it can never touch secrets or modify your tenant. ![Lighthouse AI agentic view](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.33.0-lighthouse-ai-1.webp?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=265d264d530901247f461359fa58a1aa) The chat experience is rebuilt around **persistent sessions**: conversations stream in real time, stay in your session history, can be archived, and a **sidebar chat mode** lets you ask questions from any page in the app without losing your place. ![Lighthouse AI sessions](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.33.0-lighthouse-ai-2.webp?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=155959734a2569f6c5ff30010f4c366c) You control the brain behind it. Configure one or more LLM providers — **OpenAI**, **Amazon Bedrock**, or any **OpenAI-compatible** endpoint (OpenRouter, Ollama) — with connection testing built into the setup and per-provider model selection. Add a shared **business context** (your security goals, compliance needs, organizational priorities) and every session uses it to give answers that fit your environment. ![Lighthouse AI LLM providers](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.33.0-lighthouse-ai-3.webp?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=5af1fd2604ff3ee02df232b372efb8ce) Read more in the [Lighthouse AI documentation](/getting-started/products/prowler-cloud-lighthouse) and the [multiple LLM providers guide](/user-guide/tutorials/prowler-cloud-lighthouse-multi-llm). ### 📄 Compliance PDF Reports Without Credentials Compliance PDF reports no longer require the provider's credentials to be present. Findings are now enriched from the provider metadata stored in the database, so a report still generates even after the provider secret has been deleted or its credentials have become invalid. Read more in the [compliance documentation](/user-guide/compliance/tutorials/compliance). ### ⏳ Scan Queueing Overlapping scans for the same provider now queue behind the active one instead of dispatching concurrent scan workers. Launch a manual scan while a scheduled one is running and it waits its turn. No more duplicated work or racing scans. ### 🔐 Security The Kubernetes provider credentials now reject kubeconfigs using `exec` authentication in Prowler Cloud, at the API and in the credential form, preventing user-supplied commands from running on Cloud workers. Read more in the [Kubernetes provider authentication documentation](/user-guide/providers/kubernetes/getting-started-k8s#step-2-configure-kubernetes-authentication). ### 🙌 External Contributors Thank you to our community contributors for this release! * @kratos0718 — Azure `postgresql_flexible_server_log_retention_days_greater_3` Flexible Server log retention fix ([#11761](https://github.com/prowler-cloud/prowler/pull/11761)) * @Sanjays2402 — `KeyError: 'MANUAL'` crash fix in the compliance summary table, shipped early in v5.32.1 ([#11823](https://github.com/prowler-cloud/prowler/pull/11823)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.33.0) for the complete list of changes. **v5.32.0** July 2, 2026 ### 🔎 Findings Triage > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Triage findings straight from the Findings view. Each finding gets a triage status you can move through its lifecycle: **Open → Under Review → Remediating → Risk Accepted → False Positive → Resolved** Add a triage note to record the decision, mute a finding, all from the row's actions menu. The current status shows inline on every finding row, so you keep track of what has been reviewed and stop re-checking the same issues scan after scan. ![Findings triage statuses](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.32.0-triage-1.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=e99b0c1cfb57f1cedde99620720fe8f7) The status also follows the finding automatically across scans: when a finding flips from `FAIL` to `PASS` on the next scan it moves to **Resolved**, and when it flips from `PASS` back to `FAIL` it moves to **Reopened**. You always know whether an issue is genuinely fixed or has regressed, without touching it by hand. ![Findings triage lifecycle](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.32.0-triage-2.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=a41712a0ce00b6040df537d6f164053e) Read more in the [Findings Triage documentation](/user-guide/tutorials/prowler-app-findings-triage). ### ⚙️ Scan Configuration > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Create named, reusable scan configurations from a dedicated **Scans / Configuration** page. Each configuration is YAML that follows the structure of [`prowler/config/config.yaml`](https://github.com/prowler-cloud/prowler/blob/master/prowler/config/config.yaml), so you only include the keys you want to override; the rest fall back to the built-in defaults. Values are validated on save against a per-provider, type-safe configuration schema that range-checks each field and rejects unknown keys, so a malformed config is caught before it ever reaches a scan. Attach a configuration to one or more providers so it applies on their next scan, or save it now and attach providers later. ![Scan configuration editor](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.32.0-config-1.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=c2be7ff62c112e48741d839d005e6ba6) From the Providers view you can pick which configuration a provider uses (`Default` or any of your saved ones) without leaving the page. No more passing config files around by hand. ![Scan configuration per provider](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.32.0-config-2.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=06d0d2ed5e09fe3ddbac03f1adcc6be1) Read more in the [Scan Configuration documentation](/user-guide/tutorials/prowler-app-scan-configuration). ### ✅ Per-Requirement Configuration Validation > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Compliance frameworks can now declare `ConfigRequirements` on a requirement, so it's reported as **FAIL** when its mapped checks ran under a configuration too loose to satisfy it. Even if every individual finding PASSed. This applies across all compliance outputs: CSV, OCSF, and console tables, and is the engine behind Scan Configuration's "marked as FAIL" behavior described above. ![Per-requirement configuration validation](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.32.0-per-requirement-validation.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=c5dd1c13d490cc233853d51ee16f6096) Read more in the [Configuration File documentation](/user-guide/cli/tutorials/configuration_file). ### ⏱️ Okta — Request Throttling & Retries Prowler now proactively throttles Okta API requests to stay under rate limits, with reactive retries on HTTP 429 as a safety net. Both are set in the scan configuration (or their equivalent CLI flags): * `okta_requests_per_second` (config file) / `--okta-requests-per-second` (CLI) — cap the request rate. Default: 4 req/s. * `okta_max_retries` (config file) / `--okta-retries-max-attempts` (CLI) — bound retry attempts. Default: 5. This makes large Okta scans more reliable and less likely to be rate-limited. Read more in the [Okta rate limit documentation](/user-guide/providers/okta/retry-configuration#request-throttling-requests-per-second). ### 📉 AWS — Cap Resources Scanned per Service Large AWS accounts can now cap how many resources Prowler analyzes for the highest-volume services, keeping scan time and cost under control. Set a global limit with `max_scanned_resources_per_service`, or override it per service: * EBS snapshots (`max_ebs_snapshots`) * Backup recovery points (`max_backup_recovery_points`) * CloudWatch log groups (`max_cloudwatch_log_groups`) * Lambda functions (`max_lambda_functions`) * ECS task definitions (`max_ecs_task_definitions`) * CodeArtifact packages (`max_codeartifact_packages`) Limits are **disabled by default** (`0` = unlimited); only positive values cap the analyzed resources. > [!WARNING] > > When a positive limit is set, compliance results reflect only the sampled resources, not every matching resource in the account. Read more in the [configuration file documentation](/user-guide/cli/tutorials/configuration_file#supported-aws-resource-limits). ### 🏷️ Azure — Filter by Resource Group Azure scans can now be scoped to one or more resource groups with the new `--azure-resource-group` / `--azure-resource-groups` option. This lets you run focused assessments against specific environments, teams, or workloads instead of scanning every accessible resource in the subscription. Thanks to @Legin-ML for contributing this feature! ```bash theme={null} # Single resource group prowler azure --az-cli-auth --azure-resource-group rg-prod # Multiple resource groups prowler azure --az-cli-auth --azure-resource-group rg-prod1 rg-prod2 ``` Read more in the [Azure Resource Groups documentation](/user-guide/providers/azure/resource-groups). ### 🧭 Provider Group Filter Filter the **Overview, Findings, Resources, Scans, and Providers** views by provider group. Scope the whole app to a team, an environment, or a business unit in one click instead of filtering provider by provider. ![Provider group filter](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.32.0-provider-group-filter.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=70e6f079a6f7ca65b5fcd60fdc60235e) Read more about managing provider groups in the [RBAC documentation](/user-guide/tutorials/prowler-app-rbac). ### 🔬 API — Timestamp Precision in Findings Filters The `/api/v1/findings` endpoint now accepts full timestamps on the `inserted_at` and `updated_at` filters (`filter[inserted_at__gte]`, `filter[inserted_at__lte]`, and the `updated_at` variants), so you can query narrow time windows instead of whole days. Date-only filtering keeps working, so existing integrations are unaffected. ```bash theme={null} # Findings inserted within a precise timestamp window curl --globoff \ 'http://localhost:8080/api/v1/findings?filter[inserted_at__gte]=2026-07-01T06:12:18Z&filter[inserted_at__lte]=2026-07-02T19:25:55Z' \ -H 'Authorization: Bearer ' \ -H 'Accept: application/vnd.api+json' ``` ### 🕸️ Attack Paths — Neptune as a persistent sink Attack Paths can now persist its graph in **AWS Neptune** in addition to Neo4j, selectable via `ATTACK_PATHS_SINK_DATABASE=neptune` (default `neo4j`). Cartography's per-scan ingest database stays on Neo4j. The scan task preflights the ingest database and the configured sink before ingestion, and provider graph cleanup now deletes relationships in directed batches before deleting nodes. This is the groundwork for scale: a managed graph database lets Attack Paths hold much larger graphs, extend coverage to more providers, and link resources across them so an attack path can cross provider boundaries instead of stopping at one cloud's edge. Read more in the [Attack Paths documentation](/user-guide/tutorials/prowler-app-attack-paths). ### 🔐 New Secret-Scanning Engine — Kingfisher Prowler's secret-scanning checks now run on [Kingfisher](https://github.com/mongodb/kingfisher) instead of `detect-secrets`. Scans run **fully offline by default**, and obvious placeholder values (e.g. `password123`, `changeme`) are no longer reported, cutting down false positives. Opt in to **live validation** with the new `--scan-secrets-validate` flag (or the `aws.secrets_validate` config option): Prowler checks discovered secrets against the provider APIs, and any secret confirmed to be **live is reported as critical**, so you can prioritize the credentials that actually work. > [!NOTE] > > The `detect_secrets_plugins` configuration option has been removed, as it is no longer used by the new engine. Read more in the [secret detection documentation](/user-guide/cli/tutorials/pentesting#detect-secrets). ### 🔍 Checks #### AWS * `stepfunctions_statemachine_encrypted_with_cmk` — Step Functions state machines use a customer-managed KMS key for encryption at rest instead of the default AWS-owned key. Thanks to @Sid-0602! * `waf_regional_webacl_logging_enabled` — AWS WAF Classic Regional Web ACLs have logging enabled to a Kinesis Data Firehose stream. Thanks to @Sid-0602! * **IAM privilege escalation** — the privesc checks now cover **AWS Bedrock AgentCore** paths across Runtime, Harness, Code Interpreter, and Custom Browser. Thanks to @MrCloudSec! * `apigateway_restapi_no_secrets_in_stage_variables` — scans API Gateway REST API stage variables for hardcoded passwords, API keys, and tokens. Thanks to @chirag1206! * `awslambda_function_no_secrets_in_code` — this check now supports a `secrets_ignore_files` audit-config option to skip files inside the deployment package by glob pattern (e.g. `*.deps.json`), suppressing .NET dependency-manifest false positives without masking real secrets. * `s3_bucket_object_public` — spot-checks a configurable sample of object ACLs in each bucket and flags objects granted to the `AllUsers` or `AuthenticatedUsers` groups. Disabled by default; opt in via the `s3_bucket_object_public_enabled` configuration option. Thanks to @Synchx00! #### Microsoft 365 New **Conditional Access** hardening checks: * `entra_conditional_access_policy_explicitly_targets_azure_devops` — at least one enabled policy explicitly includes the Azure DevOps cloud application, rather than relying on a broad "All cloud apps" policy. Thanks to @mzl2233! * `entra_conditional_access_policy_no_exclusion_gaps` — every user, group, role, or application excluded from an enabled policy stays in scope of another enabled policy. Thanks to @UTKARSH698 with @arieleli01212 as co-author! * `entra_conditional_access_policy_groups_management_restricted` — every security group referenced by an enabled or report-only policy is management-restricted or role-assignable. Thanks to @SAMurai-16! * `exchange_application_access_policy_restricts_mailbox_apps` — every service principal with Microsoft Graph application-level Exchange mailbox permissions is restricted by an Exchange Online Application Access Policy. Thanks to @VasistAcharya! ### 📚 Compliance #### CIS Benchmark Refresh — Six New Versions Prowler ships a coordinated refresh of the CIS Benchmarks across six providers: * **AWS** — CIS Amazon Web Services Foundations Benchmark v7.0.0, adding the new Organizations section (2.1.1-2.1.6), resource policy (2.21), web front-end access logging (4.10), and VPC Endpoints (6.8) recommendations. * **Azure** — CIS Microsoft Azure Foundations Benchmark v6.0.0. * **GCP** — CIS Google Cloud Platform Foundation Benchmark v5.0.0. * **Kubernetes** — CIS Kubernetes Benchmark v2.0.1. * **GitHub** — CIS GitHub Benchmark v1.2.0. * **Microsoft 365** — CIS Microsoft 365 Foundations Benchmark v7.0.0. #### CIS Controls v8.1 — Universal Framework A new **universal** (cross-provider) compliance framework mapping existing checks across 18 providers — AWS, Azure, GCP, Kubernetes, M365, GitHub, AlibabaCloud, OracleCloud, GoogleWorkspace, Okta, Cloudflare, Vercel, MongoDB Atlas, OpenStack, Linode, StackIT, NHN, and Scaleway — to the 18 CIS Critical Security Controls and their Safeguards. Ships with a dedicated detail view and report mapping in the UI. Read more in the [compliance documentation](/user-guide/compliance/tutorials/compliance). Explore the full compliance catalog at [Prowler Hub](https://hub.prowler.com/compliance). ### 🙌 External Contributors Thank you to our community contributors for this release! * @chirag1206 — `apigateway_restapi_no_secrets_in_stage_variables` check ([#11188](https://github.com/prowler-cloud/prowler/pull/11188)) * @MrCloudSec — AWS Bedrock AgentCore privilege escalation paths in the IAM privesc checks ([#11726](https://github.com/prowler-cloud/prowler/pull/11726)) * @Sid-0602 — `stepfunctions_statemachine_encrypted_with_cmk` ([#11538](https://github.com/prowler-cloud/prowler/pull/11538)) and `waf_regional_webacl_logging_enabled` ([#11539](https://github.com/prowler-cloud/prowler/pull/11539)) checks * @mzl2233 — `entra_conditional_access_policy_explicitly_targets_azure_devops` check ([#11182](https://github.com/prowler-cloud/prowler/pull/11182)) * @UTKARSH698 with @arieleli01212 as co-author — `entra_conditional_access_policy_no_exclusion_gaps` check ([#11577](https://github.com/prowler-cloud/prowler/pull/11577)) * @SAMurai-16 — `entra_conditional_access_policy_groups_management_restricted` check ([#11342](https://github.com/prowler-cloud/prowler/pull/11342)) * @vahidg — Azure PostgreSQL flexible server collection resilience fix ([#11595](https://github.com/prowler-cloud/prowler/pull/11595)) * @davletd — Azure `keyvault_logging_enabled` `AuditEvent` category fix ([#11660](https://github.com/prowler-cloud/prowler/pull/11660)) * @VasistAcharya — `exchange_application_access_policy_restricts_mailbox_apps` ([#11247](https://github.com/prowler-cloud/prowler/pull/11247)) * @Legin-ML — Filter scans at Resource Group level ([#10657](https://github.com/prowler-cloud/prowler/pull/10657)) * @Synchx00 — `s3_bucket_object_public` check ([#9517](https://github.com/prowler-cloud/prowler/pull/9517)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.32.0) for the complete list of changes. **v5.31.0** June 23, 2026 ### 🗓️ Flexible Scan Scheduling > [!NOTE] > > Available exclusively in **Prowler Cloud**. Prowler Local Server supports daily scans only. ![Scan scheduling from the Providers page](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.31.0-schedule-1.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=5b089d49645bbbd2f847fbcfb73b4267) You can now set a per-provider scan schedule from the Providers page. Pick a **scan time** and a **repeat cadence**: Daily, Every 48 hours, Weekly (with a day-of-week selector), or Monthly. Schedules can be edited or removed at any time, and a new scan never interrupts access to existing data. ![Schedule editor](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.31.0-schedule-2.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=419214936c76e7e91dbea7944c85adb5) All schedules are listed in one place under the **Scheduled** tab in **Scan Jobs**, showing each provider's cadence, next scan, and last scan at a glance. ![Scheduled tab in Scan Jobs](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.31.0-schedule-3.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=78dacab4f7b7c7b332d1a89b90429116) Read more in the [scan scheduling documentation](/user-guide/tutorials/prowler-scan-scheduling). ### 📚 DORA — Expanded Provider Coverage Prowler extends [**DORA**](https://www.eiopa.europa.eu/digital-operational-resilience-act-dora_en) (Digital Operational Resilience Act, Regulation (EU) 2022/2554) coverage to **Azure**, **GCP**, **Cloudflare**, and **Alibaba Cloud**, mapping each provider's existing checks across the five DORA pillars. ![DORA compliance for Alibaba Cloud](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.31.0-dora-alibaba.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=372d16aebbf267005d288e71992a6106) > [!NOTE] > > The framework follows the `_` naming convention as `DORA_2022_2554`. Read more in the [compliance documentation](/user-guide/compliance/tutorials/compliance). ### 🚀 Guided Onboarding > [!NOTE] > > Available exclusively in **Prowler Cloud**. New accounts now get a guided first-run experience. The Overview greets you with an **"Add your first provider"** prompt: connect a provider so Prowler has something to scan and assess, then get started in one click (or skip for now). ![Guided onboarding prompt](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.31.0-onboarding-1.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=ebbe4376afdd7e7bb0d606ff7865b731) From there, contextual empty states across the product point you to the next action rather than leaving you stuck. Attack Paths, for example, explains that you need a completed scan before it can build a graph and links straight to **Scan Jobs**, with a **"See how it works"** affordance for first-timers. ![Contextual empty states](https://mintcdn.com/prowler/GmKR7LrVPkti1v0q/images/changelog/v5.31.0-onboarding-2.png?fit=max\&auto=format\&n=GmKR7LrVPkti1v0q\&q=85\&s=1df47caf93e67ce1cc90fd79c09328f7) ### 🔐 Optional SAML SSO `userType` The SAML `userType` attribute is now optional. If your IdP does not send it, or sends it blank, Prowler keeps the user's existing roles unchanged instead of replacing them with a fallback role. When `userType` is provided, Prowler still maps the user to the matching role. If that role does not exist yet, Prowler creates it with read-only access: visibility over all providers, with no management permissions. Read more in the [SAML SSO documentation](/user-guide/tutorials/prowler-app-sso). ### 🏢 New Provider — Linode Prowler now scans [**Linode**](https://www.linode.com/) (Akamai Cloud), covering its administration, compute, and networking services. Thanks to @varunmamillapalli for their 1st provider in Prowler! > [!NOTE] > > Linode is not officially supported. For more information, [contact us](https://prowler.com/contact). Read more in the [Linode documentation](/user-guide/providers/linode/getting-started-linode). Explore all Linode checks at [Prowler Hub](https://hub.prowler.com/check?provider=linode). ### 🔍 Checks #### AWS **Post-Quantum Cryptography readiness** — get ahead of the migration to quantum-resistant cryptography: * `cloudfront_distributions_pqc_tls_enabled` — CloudFront distributions enforce a post-quantum TLS 1.3 security policy. * `apigateway_domain_name_pqc_tls_enabled` — API Gateway custom domain names use a post-quantum TLS security policy. * `transfer_server_pqc_ssh_kex_enabled` — Transfer Family servers use a post-quantum hybrid SSH key exchange. * `acmpca_certificate_authority_pqc_key_algorithm` — Private CA authorities use a post-quantum (ML-DSA) key algorithm (new `acmpca` service). * `rolesanywhere_trust_anchor_pqc_pki` — IAM Roles Anywhere trust anchors are backed by a post-quantum (ML-DSA) PKI (new `rolesanywhere` service). **Organization-wide governance:** * `securityhub_delegated_admin_enabled_all_regions` — Security Hub has a delegated administrator, active in all opted-in regions, with organization auto-enable on. Thanks to @ernestprovo23! * `config_delegated_admin_and_org_aggregator_all_regions` — AWS Config has a delegated administrator and an organization aggregator covering all regions. Thanks to @ernestprovo23! **Machine learning:** * `sagemaker_clarify_exists` — verifies at least one SageMaker Clarify processing job exists per scanned region, so bias-detection and model-explainability controls are in place. Thanks to @AlexanderSanin! #### Azure A large batch of new Azure checks spanning data, compute, identity, and networking: * **Cosmos DB** — automatic failover, continuous backup policy, minimum TLS 1.2, and public network access disabled. * **MySQL & PostgreSQL Flexible Servers** — geo-redundant backup and high availability. * **AKS** — auto-upgrade, Azure Monitor (Container Insights), local accounts disabled, and Microsoft Defender enabled. * **Databricks** — public network access disabled and secure cluster connectivity (no public IP). * **Defender** — CSPM on the Standard tier. * **Networking** — NSG association on subnets and DDoS Network Protection on VNets. * **Entra ID** — app registration credential expiry, users with recent sign-in and strong authentication enforcement. * **Recovery Services** — vaults with at least one protected backup item and vaults with adequate backup policy. Thanks to @s1ns3nz0 for all these contributions! #### GCP New coverage for high availability and public-exposure detection: * `cloudsql_instance_high_availability_enabled` — Cloud SQL primary instances use `REGIONAL` availability for automatic zone failover. * `cloudfunction_function_inside_vpc` — Cloud Functions use a Serverless VPC Access connector for private egress. * `cloudfunction_function_not_publicly_accessible` — detects `allUsers` / `allAuthenticatedUsers` IAM invocation bindings. * `secretmanager_secret_not_publicly_accessible` — detects Secret Manager secrets with public IAM bindings. * `secretmanager_secret_rotation_enabled` — verifies Secret Manager secrets have automatic rotation configured with a period of 90 days or less and no missed rotation. Thanks to @s1ns3nz0 for all these contributions! #### Kubernetes New core checks for container resource governance and reliability: CPU limits, CPU requests, memory limits, memory requests, fixed image tags, liveness probes, and readiness probes. Thanks to @Nikhilkumar2311 for all these contributions! #### Microsoft 365 * `entra_directory_sync_object_takeover_blocked` — hybrid Entra tenants block cloud object takeover through soft-match and hard-match directory synchronization. Thanks to @PrettyFox0 and @omobolajiadeyan! * `entra_conditional_access_policy_no_deleted_object_references` — flags Conditional Access policies that reference user, group, or role objects that no longer resolve in the directory. Thanks to @ernestprovo23! #### Oracle Cloud Infrastructure * `identity_storage_service_level_admins_scoped` — CIS 3.1 control 1.15, ensuring storage service-level administrators exclude delete permissions. Explore all checks at [Prowler Hub](https://hub.prowler.com/check). ### 🐍 Python 3.13 Support The Prowler SDK now supports **Python 3.13**. Thanks to @branchv! ### 🔐 Security Updates * **SDK** — `pytest` 8.3.5 → 9.0.3, `black` 25.1.0 → 26.3.1, `microsoft-kiota-*` → 1.9.9, and `aiohttp` → 3.14.0, patching known CVEs. * **API** — `aiohttp` → 3.14.0 and `idna` → 3.15, patching known CVEs. * **UI** — bumped vulnerable `Next.js`, React, AI SDK, `postcss`, `hono`, `qs`, `esbuild`, and Alpine OpenSSL packages; `dompurify` 3.4.2 → 3.4.10, patching XSS sanitization bypass advisories. * **Containers** — base image bumped to `python:3.12.13-slim-bookworm` (patches `libgnutls30` CVE-2026-33845 and CVE-2026-42010) and `trivy` to 0.71.0 (patches embedded `golang.org/x/crypto` and Go stdlib CVEs). ### 🙌 External Contributors Thank you to our community contributors for this release! * @varunmamillapalli — New Linode provider: administration, compute, and networking services ([#11633](https://github.com/prowler-cloud/prowler/pull/11633)) * @s1ns3nz0 — 20+ Azure & GCP checks across Cosmos DB, AKS, Databricks, Flexible Servers, Entra, networking, and GCP public-exposure * @Nikhilkumar2311 — Kubernetes resource limits, requests, image tag, and probe checks ([#11373](https://github.com/prowler-cloud/prowler/pull/11373)) * @ernestprovo23 — AWS Security Hub/Config org-wide delegated admin checks ([#11259](https://github.com/prowler-cloud/prowler/pull/11259)) and M365 conditional access check ([#11236](https://github.com/prowler-cloud/prowler/pull/11236)) * @AlexanderSanin — `sagemaker_clarify_exists` check ([#11211](https://github.com/prowler-cloud/prowler/pull/11211)) * @PrettyFox0 with @omobolajiadeyan as co-author — M365 directory sync object takeover check ([#11098](https://github.com/prowler-cloud/prowler/pull/11098)) * @branchv — Python 3.13 support ([#9293](https://github.com/prowler-cloud/prowler/pull/9293)) * @alinealfa — GCP audit-filtered aggregated sinks fix ([#11575](https://github.com/prowler-cloud/prowler/pull/11575)) * @b-abderrahmane — Configurable Celery worker concurrency ([#11075](https://github.com/prowler-cloud/prowler/pull/11075)) See the [full release notes on GitHub](https://github.com/prowler-cloud/prowler/releases/tag/5.31.0) for the complete list of changes. **Earlier releases** Release notes for v5.30.0 and earlier, along with every patch release, are on [GitHub Releases](https://github.com/prowler-cloud/prowler/releases). # AI Skills System Source: https://docs.prowler.com/developer-guide/ai-skills This guide explains the AI Skills system that provides on-demand context and patterns to AI agents working with the Prowler codebase. > [!NOTE] > > **What are AI Skills?** Skills are structured instructions that help AI agents (Claude Code, Cursor, Copilot, etc.) understand Prowler's conventions, patterns, and best practices. Skills live in the [`skills/`](https://github.com/prowler-cloud/prowler/tree/master/skills) directory of the Prowler OSS repository. Each skill is a folder containing a `SKILL.md` file with its patterns and metadata. ## Installation To enable skills for the supported AI coding assistants, run the setup script from the repository root: ```bash theme={null} ./skills/setup.sh ``` The script creates symlinks so each tool finds the skills in its expected location: | Tool | Created by setup | | - | - | | Claude Code | `.claude/skills/` symlink and `CLAUDE.md` | | Gemini CLI | `.gemini/skills/` symlink and `GEMINI.md` | | Codex (OpenAI) | `.agents/skills/` symlink, plus the legacy `.codex/skills/` (uses `AGENTS.md` natively) | | GitHub Copilot | `.github/copilot-instructions.md` symlink to `AGENTS.md` | After running the setup, restart the AI coding assistant to load the skills. ## Using Skills AI agents discover skills automatically and load them when a request matches a skill trigger. To load a skill manually during a session, point the agent to the skill's `SKILL.md` file: ```text theme={null} Read skills/{skill-name}/SKILL.md ``` For the full list of available skills, their triggers, and the Auto-invoke mappings, see the [`skills/README.md`](https://github.com/prowler-cloud/prowler/blob/master/skills/README.md) and [`AGENTS.md`](https://github.com/prowler-cloud/prowler/blob/master/AGENTS.md) in the repository. ## Available Skills | Type | Skills | | - | - | | **Generic** | typescript, react-19, nextjs-16, tailwind-4, pytest, playwright, django-drf, zod-4, zustand-5, ai-sdk-5, vitest, tdd | | **Prowler** | prowler, prowler-sdk-check, prowler-api, prowler-ui, prowler-mcp, prowler-provider, prowler-compliance, prowler-compliance-review, prowler-docs, prowler-pr, prowler-ci, prowler-attack-paths-query | | **Testing** | prowler-test-sdk, prowler-test-api, prowler-test-ui | | **Meta** | skill-creator, skill-sync | > [!NOTE] > > This table is a snapshot. The repository is the source of truth: see [`skills/README.md`](https://github.com/prowler-cloud/prowler/blob/master/skills/README.md) for the current, complete list. ## Skill Structure Each skill follows the [Agent Skills spec](https://agentskills.io): ```text theme={null} skills/{skill-name}/ ├── SKILL.md # Patterns, rules, decision trees ├── assets/ # Code templates, schemas └── references/ # Links to local docs (single source of truth) ``` ## Key Design Decisions 1. **Self-contained skills** - Critical patterns inline for fast loading 2. **Local doc references** - No web URLs, points to `docs/developer-guide/*.mdx` 3. **Single source of truth** - Skills reference docs, no duplication 4. **On-demand loading** - AI loads only what's needed for the task ## Creating New Skills Use the `skill-creator` meta-skill to create new skills that follow the Agent Skills spec. See [`AGENTS.md`](https://github.com/prowler-cloud/prowler/blob/master/AGENTS.md) for the full list of available skills and their triggers. ## How Skills Work The diagrams below explain the internals of the skill system. They are useful for understanding the design, but are not required to install or use skills. ### Architecture Overview ```mermaid theme={null} graph LR subgraph FLOW["AI Skills Architecture"] A["AI Agent"] -->|"1. matches trigger"| B["AGENTS.md"] B -->|"2. loads"| C["Skill"] C -->|"3. provides"| D["Patterns
Templates
Commands"] C -->|"4. references"| E["Local Docs"] D --> F["Correct Output"] E --> F end style A fill:#1e3a5f,stroke:#4a9eff,color:#fff style B fill:#5c4d1a,stroke:#ffd700,color:#fff style C fill:#1a4d1a,stroke:#4caf50,color:#fff style E fill:#4a1a4d,stroke:#ba68c8,color:#fff style F fill:#1a4d2e,stroke:#66bb6a,color:#fff ``` ### Request Lifecycle ```mermaid theme={null} sequenceDiagram participant U as User participant A as AI Agent participant R as AGENTS.md participant S as Skill participant AS as assets/ participant RF as references/ participant D as Local Docs U->>A: "Create an AWS security check" Note over A: Analyze request context A->>R: Find matching skill trigger R-->>A: prowler-sdk-check matches A->>S: Load SKILL.md S-->>A: Patterns, rules, templates, commands Note over A: Need code template? A->>AS: Read assets/aws_check.py AS-->>A: Check implementation template Note over A: Need more details? A->>RF: Read references/metadata-docs.md RF-->>A: Points to local docs A->>D: Read docs/developer-guide/checks.mdx D-->>A: Full documentation Note over A: Execute with full context A->>U: Creates check with correct patterns ``` ### With and Without Skills ```mermaid theme={null} graph TD subgraph COMPARISON["BEFORE vs AFTER"] direction LR subgraph BEFORE["Without Skills"] B1["AI guesses conventions"] B2["Wrong structure"] B3["Multiple iterations"] B4["Web searches for docs"] B5["Inconsistent patterns"] end subgraph AFTER["With Skills"] A1["AI loads exact patterns"] A2["Correct structure"] A3["First-time right"] A4["Local docs referenced"] A5["Consistent patterns"] end end style BEFORE fill:#5c1a1a,stroke:#ef5350,color:#fff style AFTER fill:#1a4d1a,stroke:#66bb6a,color:#fff ``` ### Full Component Map ```mermaid theme={null} flowchart TB subgraph ENTRY["ENTRY POINT"] AGENTS["AGENTS.md
━━━━━━━━━━━━━━━━━
• Available skills registry
• Skill → Trigger mapping
• Component navigation"] end subgraph SKILLS["SKILLS LIBRARY"] direction TB subgraph GENERIC["Generic Skills"] G1["typescript"] G2["react-19"] G3["nextjs-16"] G4["tailwind-4"] G5["pytest"] G6["playwright"] G7["django-drf"] G8["zod-4"] G9["zustand-5"] G10["ai-sdk-5"] end subgraph PROWLER["Prowler Skills"] P1["prowler"] P2["prowler-sdk-check"] P3["prowler-api"] P4["prowler-ui"] P5["prowler-mcp"] P6["prowler-provider"] P7["prowler-compliance"] P8["prowler-compliance-review"] P9["prowler-docs"] P10["prowler-pr"] P11["prowler-ci"] end subgraph TESTING["Testing Skills"] T1["prowler-test-sdk"] T2["prowler-test-api"] T3["prowler-test-ui"] end subgraph META["Meta Skills"] M1["skill-creator"] M2["skill-sync"] end end subgraph STRUCTURE["SKILL STRUCTURE"] direction LR SKILLMD["SKILL.md
━━━━━━━━━━━━━━
• Frontmatter
• Critical patterns
• Decision trees
• Code examples
• Commands
• Keywords"] ASSETS["assets/
━━━━━━━━━━━━━━
• Code templates
• JSON schemas
• Config examples"] REFS["references/
━━━━━━━━━━━━━━
• Local doc paths
• No web URLs
• Single source"] end subgraph DOCS["DOCUMENTATION"] direction TB DD["docs/developer-guide/"] D1["checks.mdx"] D2["unit-testing.mdx"] D3["provider.mdx"] D4["mcp-server.mdx"] D5["..."] DD --> D1 DD --> D2 DD --> D3 DD --> D4 DD --> D5 end ENTRY --> SKILLS SKILLS --> STRUCTURE SKILLMD --> ASSETS SKILLMD --> REFS REFS -.->|"points to"| DOCS style ENTRY fill:#1e3a5f,stroke:#4a9eff,color:#fff style GENERIC fill:#5c4d1a,stroke:#ffd700,color:#fff style PROWLER fill:#1a4d1a,stroke:#66bb6a,color:#fff style TESTING fill:#4d1a3d,stroke:#f06292,color:#fff style META fill:#4a1a4d,stroke:#ba68c8,color:#fff style STRUCTURE fill:#5c3d1a,stroke:#ffb74d,color:#fff style DOCS fill:#1a3d4d,stroke:#4dd0e1,color:#fff ``` # Alibaba Cloud Provider Source: https://docs.prowler.com/developer-guide/alibabacloud-details This page details the [Alibaba Cloud](https://www.alibabacloud.com/) provider implementation in Prowler. By default, Prowler will audit all the Alibaba Cloud regions that are available. To configure it, follow the [Alibaba Cloud getting started guide](/user-guide/providers/alibabacloud/getting-started-alibabacloud). ## Alibaba Cloud Provider Classes Architecture The Alibaba Cloud provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the Alibaba Cloud-specific implementation, highlighting how the generic provider concepts are realized for Alibaba Cloud in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### Main Class * **Location:** [`prowler/providers/alibabacloud/alibabacloud_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/alibabacloud/alibabacloud_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for Alibaba Cloud-specific logic, session management, credential validation, and configuration. * **Key Alibaba Cloud Responsibilities:** * Initializes and manages Alibaba Cloud sessions (supports Access Keys, STS Temporary Credentials, RAM Role Assumption, ECS RAM Role, OIDC Authentication, and Credentials URI). * Validates credentials using STS GetCallerIdentity. * Loads and manages configuration, mutelist, and fixer settings. * Discovers and manages Alibaba Cloud regions. * Provides properties and methods for downstream Alibaba Cloud service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/alibabacloud/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/alibabacloud/models.py) * **Purpose:** Define structured data for Alibaba Cloud identity, session, credentials, and region info. * **Key Alibaba Cloud Models:** * `AlibabaCloudCallerIdentity`: Stores caller identity information from STS GetCallerIdentity (account\_id, principal\_id, arn, identity\_type). * `AlibabaCloudIdentityInfo`: Holds Alibaba Cloud identity metadata including account ID, user info, profile, and audited regions. * `AlibabaCloudCredentials`: Stores credentials (access\_key\_id, access\_key\_secret, security\_token). * `AlibabaCloudRegion`: Represents an Alibaba Cloud region with region\_id and region\_name. * `AlibabaCloudSession`: Manages the session and provides methods to create service clients. ### `AlibabaCloudService` (Service Base Class) * **Location:** [`prowler/providers/alibabacloud/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/alibabacloud/lib/service/service.py) * **Purpose:** Abstract base class that all Alibaba Cloud service-specific classes inherit from. This implements the generic service pattern (described in [service page](/developer-guide/services#service-base-class)) specifically for Alibaba Cloud. * **Key Alibaba Cloud Responsibilities:** * Receives an `AlibabacloudProvider` instance to access session, identity, and configuration. * Manages regional clients for services that are region-specific. * Provides `__threading_call__` method to make API calls in parallel by region or resource. * Exposes common audit context (`audited_account`, `audited_account_name`, `audit_resources`, `audit_config`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/alibabacloud/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/alibabacloud/exceptions/exceptions.py) * **Purpose:** Custom exception classes for Alibaba Cloud-specific error handling. * **Key Alibaba Cloud Exceptions:** * `AlibabaCloudClientError`: General client errors * `AlibabaCloudNoCredentialsError`: No credentials found * `AlibabaCloudInvalidCredentialsError`: Invalid credentials provided * `AlibabaCloudSetUpSessionError`: Session setup failures * `AlibabaCloudAssumeRoleError`: RAM role assumption failures * `AlibabaCloudInvalidRegionError`: Invalid region specified * `AlibabaCloudHTTPError`: HTTP/API errors ### Session and Utility Helpers * **Location:** [`prowler/providers/alibabacloud/lib/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/alibabacloud/lib/) * **Purpose:** Helpers for argument parsing, mutelist management, and other cross-cutting concerns. ## Specific Patterns in Alibaba Cloud Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/alibabacloud/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/alibabacloud/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and taking other services already implemented as reference. In next subsection you can find a list of common patterns that are used across all Alibaba Cloud services. ### Alibaba Cloud Service Common Patterns * Services communicate with Alibaba Cloud using the official Alibaba Cloud Python SDKs. Documentation for individual services can be found in the [Alibaba Cloud SDK documentation](https://www.alibabacloud.com/help/en/sdk). * Every Alibaba Cloud service class inherits from `AlibabaCloudService`, ensuring access to session, identity, configuration, and client utilities. * The constructor (`__init__`) always calls `super().__init__` with the service name, provider, and optionally `global_service=True` for services that are not regional (e.g., RAM). * Resource containers **must** be initialized in the constructor. For regional services, resources are typically stored in dictionaries keyed by region and resource ID. * All Alibaba Cloud resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * Alibaba Cloud SDK functions are wrapped in try/except blocks, with specific handling for errors, always logging errors. * Regional services use `self.regional_clients` to maintain clients for each audited region. * The `__threading_call__` method is used for parallel execution across regions or resources. ### Example Service Implementation ```python theme={null} from prowler.lib.logger import logger from prowler.providers.alibabacloud.lib.service.service import AlibabaCloudService class MyService(AlibabaCloudService): def __init__(self, provider): # Initialize parent class with service name super().__init__("myservice", provider) # Initialize resource containers self.resources = {} # Discover resources using threading self.__threading_call__(self._describe_resources) def _describe_resources(self, regional_client): try: region = regional_client.region response = regional_client.describe_resources() for resource in response.body.resources: self.resources[resource.id] = MyResource( id=resource.id, name=resource.name, region=region, # ... other attributes ) except Exception as error: logger.error( f"{error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) ``` ## Specific Patterns in Alibaba Cloud Checks The Alibaba Cloud checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/alibabacloud/services/ram/ram_no_root_access_key/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/alibabacloud/services/ram/ram_no_root_access_key)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is following the [check implementation documentation](/developer-guide/checks#creating-a-check) and taking other similar checks as reference. ### Check Report Class The `CheckReportAlibabaCloud` class models a single finding for an Alibaba Cloud resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `CheckReportAlibabaCloud` extends the base report structure with Alibaba Cloud-specific fields, enabling detailed tracking of the resource, resource ID, ARN, and region associated with each finding. #### Constructor and Attribute Population When you instantiate `CheckReportAlibabaCloud`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its Alibaba Cloud-specific attributes from the resource, using the following logic: * **`resource_id`**: * Uses `resource.id` if present. * Otherwise, uses `resource.name` if present. * Defaults to an empty string if not available. * **`resource_arn`**: * Uses `resource.arn` if present. * Defaults to an empty string if not available. * **`region`**: * Uses `resource.region` if present. * Defaults to an empty string if not available. If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from which you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} from prowler.lib.check.models import Check, CheckReportAlibabaCloud from prowler.providers.alibabacloud.services.myservice.myservice_client import myservice_client class myservice_example_check(Check): def execute(self) -> list[CheckReportAlibabaCloud]: findings = [] for resource in myservice_client.resources.values(): report = CheckReportAlibabaCloud( metadata=self.metadata(), resource=resource ) report.region = resource.region report.resource_id = resource.id report.resource_arn = f"acs:myservice::{myservice_client.audited_account}:resource/{resource.id}" if resource.is_compliant: report.status = "PASS" report.status_extended = f"Resource {resource.name} is compliant." else: report.status = "FAIL" report.status_extended = f"Resource {resource.name} is not compliant." findings.append(report) return findings ``` ## Authentication Methods The Alibaba Cloud provider supports multiple authentication methods, prioritized in the following order: 1. **Credentials URI** - Retrieve credentials from an external URI endpoint 2. **OIDC Role Authentication** - For applications running in ACK with RRSA enabled 3. **ECS RAM Role** - For ECS instances with attached RAM roles 4. **RAM Role Assumption** - Cross-account access with role assumption 5. **STS Temporary Credentials** - Pre-obtained temporary credentials 6. **Permanent Access Keys** - Static access key credentials 7. **Default Credential Chain** - Automatic credential discovery For detailed authentication configuration, see the [Authentication documentation](/user-guide/providers/alibabacloud/authentication). ## Regions Alibaba Cloud has multiple regions across the globe. By default, Prowler audits all available regions. You can specify specific regions using the `--region` CLI argument: ```bash theme={null} prowler alibabacloud --region cn-hangzhou cn-shanghai ``` The list of supported regions is maintained in [`prowler/providers/alibabacloud/config.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/alibabacloud/config.py). # Attack Paths Queries Source: https://docs.prowler.com/developer-guide/attack-paths-queries This guide explains how to write and maintain Prowler Attack Paths queries: the read-only openCypher queries that traverse the Cartography-ingested cloud graph to detect privilege escalation chains, network exposure, and other graph-shaped security risks. > [!NOTE] > > **New to Attack Paths?** Start with the user documentation: > > * [Attack Paths](/user-guide/tutorials/prowler-app-attack-paths) - What Attack Paths detects, how to run built-in queries, and how to explore the resulting graph. > * [Writing Custom openCypher Queries](/user-guide/tutorials/prowler-app-attack-paths#writing-custom-opencypher-queries) - Run ad-hoc read-only queries from the Prowler App. ## Introduction Attack Paths queries run against a property graph populated by [Cartography](https://github.com/cartography-cncf/cartography), an open-source graph ingestion framework, and enriched with Prowler findings. Every query is read-only openCypher (Version 9) so it runs on both the Neo4j and Amazon Neptune sinks. Two categories of query exist, each with a different isolation model: | | Predefined queries | Custom queries | | - | - | - | | Where they live | `api/src/backend/api/attack_paths/queries/{provider}.py` | User-supplied through the custom query API endpoint | | Provider isolation | `AWSAccount {id: $provider_uid}` anchor plus path connectivity | Automatic `_Provider_{uuid}` label injection by `cypher_sanitizer.py` | | What to write | Chain every `MATCH` from the `aws` variable | Plain Cypher, no isolation boilerplate | | Internal labels | Never use | Never use (system-injected) | For **predefined queries**, every node must be reachable from the `AWSAccount` root through graph traversal. That reachability is the isolation boundary. For **custom queries**, the runner injects a `_Provider_{uuid}` label into every node pattern, and a post-query filter handles edge cases, so query authors write natural Cypher without isolation boilerplate. The rest of this guide focuses on predefined queries, though the graph model, list-property handling, and compatibility rules apply to both. ## The Graph Model ### Cartography Schema Node labels, relationship types, and properties follow the upstream Cartography schema for each provider. Do not guess them, fetch the schema for the pinned Cartography version: ```bash theme={null} grep cartography api/pyproject.toml ``` Then read the schema for that exact tag: ```text theme={null} # Git pin (prowler-cloud/cartography@): https://raw.githubusercontent.com/prowler-cloud/cartography/refs/tags//docs/root/modules/{provider}/schema.md # PyPI pin (cartography==): https://raw.githubusercontent.com/cartography-cncf/cartography/refs/tags//docs/root/modules/{provider}/schema.md ``` The public schema reference for AWS is available at [Cartography AWS Schema](https://cartography-cncf.github.io/cartography/modules/aws/schema.html). ### Prowler-Specific Additions The Prowler sync task enriches the Cartography graph with the following labels and relationships. These are not part of the upstream schema: | Label / Relationship | Description | | - | - | | `ProwlerFinding` | Finding node (`status`, `severity`, `check_id`) | | `Internet` | Internet sentinel node used to model public exposure | | `CAN_ACCESS` | `(Internet)-[:CAN_ACCESS]->(resource)` exposure edge | | `HAS_FINDING` | `(resource)-[:HAS_FINDING]->(:ProwlerFinding)` finding link | | `TRUSTS_AWS_PRINCIPAL` | Role trust relationship | | `STS_ASSUMEROLE_ALLOW` | Principal can assume a role | ### Internal Isolation Labels The sync layer also adds internal labels used only for tenant and provider isolation: `_ProviderResource`, `_AWSResource`, `_Tenant_*`, and `_Provider_*`. These must never appear in query text, predefined or custom. The runner applies isolation automatically. ## Query Structure ### Provider Scoping Parameter | Parameter | Property | Used on | Purpose | | - | - | - | - | | `$provider_uid` | `id` | `AWSAccount` | Scopes the query to a specific account | The runner binds `$provider_uid` automatically. Every other node is isolated by path connectivity from the `AWSAccount` anchor. ### Imports ```python theme={null} from api.attack_paths.queries.types import ( AttackPathsQueryAttribution, AttackPathsQueryDefinition, AttackPathsQueryParameterDefinition, ) from tasks.jobs.attack_paths.config import PROWLER_FINDING_LABEL ``` Always reference `PROWLER_FINDING_LABEL` through f-string interpolation, never hardcode `"ProwlerFinding"`. ### Definition Fields * **id**: kebab-case `{provider}-{category}-{description}`, e.g. `aws-ec2-privesc-passrole-iam`. * **name**: short, human-friendly label. Sourced queries append the reference ID: `"EC2 Instance Launch with Privileged Role (EC2-001)"`. * **short\_description**: one sentence, no technical permissions. * **description**: full technical explanation, plain text. * **provider**: `aws`, `azure`, `gcp`, `kubernetes`, or `github`. * **cypher**: f-string Cypher body. Literal `{` and `}` are escaped as `{{` and `}}`. * **parameters**: `parameters=[]` when the query takes no input. * **attribution**: optional `AttackPathsQueryAttribution(text, link)` for sourced queries. The `link` uses the lowercase ID. Append the constant to the `{PROVIDER}_QUERIES` list at the bottom of the provider file. ## The Predefined Query Template The canonical shape combines a principal walk, an optional target walk, deduplicated nodes, and a typed finding overlay: ```python theme={null} AWS_QUERY_NAME = AttackPathsQueryDefinition( id="aws-kebab-case-name", name="Label (REFERENCE_ID)", short_description="One sentence.", description="Full technical explanation.", attribution=AttackPathsQueryAttribution( text="pathfinding.cloud - REFERENCE_ID - permission", link="https://pathfinding.cloud/paths/reference_id_lowercase", ), provider="aws", cypher=f""" // Find principals with the source permission MATCH path_principal = (aws:AWSAccount {{id: $provider_uid}})--(principal:AWSPrincipal)-[:POLICY]->(policy:AWSPolicy)-[:STATEMENT]->(stmt:AWSPolicyStatement {{effect: 'Allow'}}) MATCH (stmt)-[:HAS_ACTION]->(act:AWSPolicyStatementActionItem) WHERE toLower(act.value) IN ['permission_lowercase', 'service:*'] OR act.value = '*' WITH DISTINCT aws, principal, stmt, path_principal // Pre-aggregate the statement's resource values (see "Avoiding Cartesian Products") MATCH (stmt)-[:HAS_RESOURCE]->(res:AWSPolicyStatementResourceItem) WITH aws, path_principal, collect(DISTINCT res.value) AS res_values WITH aws, path_principal, res_values, ('*' IN res_values) AS res_wildcard // Match each target once against the in-memory resource list MATCH path_target = (aws)--(target_role:AWSRole) WITH path_principal, path_target, res_values, res_wildcard, target_role.name AS rname, target_role.arn AS rarn WHERE res_wildcard OR size([rv IN res_values WHERE rv CONTAINS rname OR rarn CONTAINS rv]) > 0 WITH DISTINCT path_principal, path_target WITH collect(path_principal) + collect(path_target) AS paths UNWIND paths AS p UNWIND nodes(p) AS n WITH paths, collect(DISTINCT n) AS unique_nodes UNWIND unique_nodes AS n OPTIONAL MATCH (n)-[pfr:HAS_FINDING]-(pf:{PROWLER_FINDING_LABEL} {{status: 'FAIL'}}) RETURN paths, collect(DISTINCT pf) as dpf, collect(DISTINCT pfr) as dpfr """, parameters=[], ) ``` Key points: * The principal walk types the `POLICY` and `STATEMENT` hops. Both are low-fan-out (each principal has a handful of policies; each policy a handful of statements), so the typed edge lets the planner cost a cheap inline filter. * The `(aws)--` hub hops stay anonymous. `AWSAccount` is a high-degree node that fans out to every principal, role, policy, and resource in the account; typing those edges forces the planner to enumerate from the hub and collapses performance on multi-tenant Neptune. * Other relationship types appear only where the file's existing queries already use one (`TRUSTS_AWS_PRINCIPAL`, `STS_ASSUMEROLE_ALLOW`, `MEMBER_AWS_GROUP`, `HAS_EXECUTION_ROLE`). * The finding probe is typed `:HAS_FINDING` and left undirected. The type lets Neptune apply an inline edge filter; the missing direction matches the convention of the rest of the file. * Collapse duplicate rows after each permission gate with `WITH DISTINCT`, carrying only the variables needed by later clauses. * The `RETURN` shape `paths, dpf, dpfr` is the contract the serializer and visualizer depend on. Do not change it. ## Avoiding Cartesian Products The most common performance defect in Attack Paths queries is a Cartesian product between a target set and a policy statement's resource items. When the two are written as independent `MATCH` clauses, the planner pairs every target with every resource item before any filter runs. On accounts with many IAM principals, that multiplies into hundreds of thousands of rows and the query errors or times out. ### The Pattern That Causes It ```cypher theme={null} // One row per (target_role x resource_item): a Cartesian product MATCH path_target = (aws)--(target_role:AWSRole) MATCH (stmt)-[:HAS_RESOURCE]->(res:AWSPolicyStatementResourceItem) WHERE res.value = '*' OR res.value CONTAINS target_role.name OR target_role.arn CONTAINS res.value ``` The two `MATCH` clauses share no relationship, so the engine enumerates all targets multiplied by all resource items, applies a non-indexable `CONTAINS` to each pair, then expands the finding overlay for every surviving row. Cost grows with `targets × resources`, and a second constrained statement (`stmt2`) multiplies it again. ### The Pattern That Avoids It Collect the statement's resource values into a list once, then match each target a single time against that in-memory list: ```cypher theme={null} // Pre-aggregate the statement's resource values into a list MATCH (stmt)-[:HAS_RESOURCE]->(res:AWSPolicyStatementResourceItem) WITH aws, path_principal, collect(DISTINCT res.value) AS res_values WITH aws, path_principal, res_values, ('*' IN res_values) AS res_wildcard // Match each target once; bind name/arn to locals so the predicate reads them once MATCH path_target = (aws)--(target_role:AWSRole) WITH path_principal, path_target, res_values, res_wildcard, target_role.name AS rname, target_role.arn AS rarn WHERE res_wildcard OR size([rv IN res_values WHERE rv CONTAINS rname OR rarn CONTAINS rv]) > 0 ``` Cost now grows with `targets + resources` (linear) rather than `targets × resources`. The rewrite is a pure algebraic identity: the result set is unchanged. Guidelines: * **Aggregate resources before matching targets, not after.** `collect(DISTINCT res.value)` reduces the resource items to a single list per statement. * **Short-circuit the wildcard grant** with `('*' IN res_values)`. When a statement grants `*`, every target matches, so the list scan is skipped entirely. * **Bind `target.name` and `target.arn` to local variables** in a `WITH` before the predicate. The list comprehension then reads each once per target instead of re-reading the property store once per resource value. * **Use `size([... ]) > 0`, not `any(...)`.** The `any()`, `all()`, and `none()` predicate functions are not part of the openCypher specification and fail on Amazon Neptune. See [openCypher Compatibility](#opencypher-compatibility). * **For two-statement queries**, aggregate each statement's resources into its own list (`res_values`, `res2_values`) and combine the two `size([... ]) > 0` checks with `AND`. Every IAM privilege escalation query in `aws.py` uses this pattern. The lateral-movement variants that constrain the target with a relationship (`STS_ASSUMEROLE_ALLOW`, `TRUSTS_AWS_PRINCIPAL`) already limit the target set before the resource filter, which keeps them efficient without further aggregation. ## Privilege Escalation Sub-Patterns Four `path_target` shapes cover the common escalation types. Each shares the canonical template's `path_principal`, the resource pre-aggregation, the deduplication tail, and the `RETURN`; only the `path_target` `MATCH` and its resource predicate differ. | Sub-pattern | Target | `path_target` shape | Example | | - | - | - | - | | Self-escalation | Principal's own policies | `(aws)--(target_policy:AWSPolicy)--(principal)` | IAM-001 | | Lateral to user | Other IAM users | `(aws)--(target_user:AWSUser)` | IAM-002 | | Assume-role lateral | Assumable roles | `(aws)--(target_role:AWSRole)-[:STS_ASSUMEROLE_ALLOW]-(principal)` | IAM-014 | | PassRole plus service | Service-trusting roles | `(aws)--(target_role:AWSRole)-[:TRUSTS_AWS_PRINCIPAL]-(:AWSPrincipal {arn: '{service}.amazonaws.com'})` | EC2-001 | **Multi-permission queries** (for example PassRole plus a service-create action) add permission gates before `path_target`. Reuse the per-query counter for new variables (`act2`, `policy2`, `stmt2`) and collapse rows after each gate: ```cypher theme={null} MATCH (principal)-[:POLICY]->(policy2:AWSPolicy)-[:STATEMENT]->(stmt2:AWSPolicyStatement {effect: 'Allow'}) MATCH (stmt2)-[:HAS_ACTION]->(act2:AWSPolicyStatementActionItem) WHERE toLower(act2.value) IN ['service:*', 'service:createsomething'] OR act2.value = '*' WITH DISTINCT aws, principal, stmt, stmt2, path_principal ``` When a permission is an existence-only gate whose statement resource is not checked later, keep the policy and statement anonymous and carry only the variables still needed: ```cypher theme={null} MATCH (principal)-[:POLICY]->(:AWSPolicy)-[:STATEMENT]->(:AWSPolicyStatement {effect: 'Allow'})-[:HAS_ACTION]->(act3:AWSPolicyStatementActionItem) WHERE toLower(act3.value) IN ['service:*', 'service:othersomething'] OR act3.value = '*' WITH DISTINCT aws, principal, stmt, path_principal ``` ## Network Exposure Pattern The Internet node is reached through `CAN_ACCESS` from an already-scoped resource, never as a standalone lookup: ```python theme={null} cypher=f""" // Resource scoped through the account anchor MATCH path = (aws:AWSAccount {{id: $provider_uid}})--(resource:EC2Instance) WHERE resource.exposed_internet = true // Internet node reached through path connectivity from the resource OPTIONAL MATCH (internet:Internet)-[can_access:CAN_ACCESS]->(resource) WITH collect(path) AS paths, head(collect(internet)) AS internet, collect(can_access) AS can_access UNWIND paths AS p UNWIND nodes(p) AS n WITH paths, internet, can_access, collect(DISTINCT n) AS unique_nodes UNWIND unique_nodes AS n OPTIONAL MATCH (n)-[pfr:HAS_FINDING]-(pf:{PROWLER_FINDING_LABEL} {{status: 'FAIL'}}) RETURN paths, collect(DISTINCT pf) as dpf, collect(DISTINCT pfr) as dpfr, internet, can_access """ ``` The `CAN_ACCESS` edge stays typed and directed (`-[:CAN_ACCESS]->`); that is its canonical sync-time orientation. Network-exposure queries extend the `RETURN` contract with `internet, can_access`. ## Working with List-Typed Properties Some Cartography node properties carry a list of values: `AWSPolicyStatement.action`, `AWSPolicyStatement.resource`, `AWSPolicyStatement.notaction`, `AWSPolicyStatement.notresource`, `KMSKey.encryption_algorithms`, `CloudFrontDistribution.aliases`, the container-definition lists on `ECSContainerDefinition`, and many others. The graph models each such property as a set of child item nodes connected to the parent by a typed edge. Queries reach the values by traversing the edge; the parent does not carry the list as a single field. ### Naming Convention For a list-typed parent property the sink stores: * **Child label**: `Item`. Example: `AWSPolicyStatement.resource` becomes `AWSPolicyStatementResourceItem`. * **Edge type**: `HAS_`. Example: `resource` becomes `HAS_RESOURCE`. * **Child property**: `value`, a single scalar string per list element. For list-of-dict properties (rare; for example `SecretsManagerSecretVersion.tags`) the child carries the original dict keys as named fields per the catalog's `field_map`. ### Variable Naming for Child-Item Matches `aws.py` uses a per-query counter for each `HAS_*` traversal so chained matches stay unambiguous. The counter resets at the top of every query. | Edge | First | Second | Third | | - | - | - | - | | `HAS_ACTION` | `act` | `act2` | `act3` | | `HAS_RESOURCE` | `res` | `res2` | `res3` | | `HAS_NOTACTION` | `nact` | `nact2` | `nact3` | | `HAS_NOTRESOURCE` | `nres` | `nres2` | `nres3` | ### Matching an Action To find statements that grant `iam:PassRole`, `iam:*`, or `*`, traverse the `HAS_ACTION` edge in its own `MATCH` clause and apply the predicate in the attached `WHERE`: ```cypher theme={null} MATCH (stmt:AWSPolicyStatement {effect: 'Allow'}) MATCH (stmt)-[:HAS_ACTION]->(act:AWSPolicyStatementActionItem) WHERE toLower(act.value) IN ['iam:passrole', 'iam:*'] OR act.value = '*' ``` The literal-action list is case-folded with `toLower(act.value)` because IAM authors mix case (`iam:PassRole`, `iam:passrole`); the `*` wildcard never lower-cases. ### Matching a Resource Against a Target To find statements whose resource can target a specific node, pre-aggregate the resource values and test the target against the list once (see [Avoiding Cartesian Products](#avoiding-cartesian-products)): ```cypher theme={null} MATCH (stmt)-[:HAS_RESOURCE]->(res:AWSPolicyStatementResourceItem) WITH aws, path_principal, collect(DISTINCT res.value) AS res_values WITH aws, path_principal, res_values, ('*' IN res_values) AS res_wildcard MATCH path_target = (aws)--(target_role:AWSRole) WITH path_principal, path_target, res_values, res_wildcard, target_role.name AS rname, target_role.arn AS rarn WHERE res_wildcard OR size([rv IN res_values WHERE rv CONTAINS rname OR rarn CONTAINS rv]) > 0 ``` Three predicates cover the resource cases: full wildcard (`*`), a pattern containing the target name (`arn:aws:iam::*:role/admin*`), and a pattern that is a prefix or component of the actual ARN. ### Every-Item and Any-Item Predicates on a Custom Query Custom queries can express list predicates directly with pattern comprehensions. To check whether *every* item satisfies a predicate, count the counter-examples and require zero, together with a guard that ensures at least one item is attached: ```cypher theme={null} MATCH (stmt:AWSPolicyStatement) WHERE size([ (stmt)-[:HAS_ACTION]->(a:AWSPolicyStatementActionItem) WHERE NOT toLower(a.value) STARTS WITH 's3:' | a ]) = 0 AND size([(stmt)-[:HAS_ACTION]->(a:AWSPolicyStatementActionItem) | a]) > 0 RETURN stmt LIMIT 25 ``` To return the list of values directly, collect them from the child items: ```cypher theme={null} MATCH (stmt:AWSPolicyStatement {effect: 'Allow'}) OPTIONAL MATCH (stmt)-[:HAS_ACTION]->(a:AWSPolicyStatementActionItem) RETURN stmt, collect(a.value) AS actions LIMIT 25 ``` ### Catalog of List Properties The provider catalog lives in `api/src/backend/tasks/jobs/attack_paths/provider_config.py` (`AWS_NORMALIZED_LISTS`). Beyond policy statements it includes KMS algorithms, ECS container-definition lists (`entry_point`, `command`, `links`, `dns_servers`, and others), CloudFront aliases, Inspector finding URL and vulnerability lists, and RDS event-subscription categories. To query a list property that is not in the catalog, add an entry there first so the sync layer materializes it. Properties absent from the catalog are serialized to a comma-delimited string and emit a one-time warning during sync. ## Working with JSON-Encoded Properties Some Cartography properties represent nested objects, most notably `condition` on `AWSPolicyStatement` and `S3PolicyStatement` nodes. To keep the schema portable across graph backends, object-typed properties are stored as JSON-encoded strings: ``` '{"StringEquals":{"aws:SourceAccount":"123456789012"}}' ``` No JSON parser is available at query time, so use `CONTAINS` for substring checks against keys or known values: ```cypher theme={null} MATCH (stmt:AWSPolicyStatement) WHERE stmt.effect = 'Allow' AND stmt.condition CONTAINS '"aws:SourceAccount"' RETURN stmt LIMIT 25 ``` When a query needs to inspect the structured members of a condition (for example, to evaluate every operator and key), fetch the rows first and parse the JSON in application code. Cypher cannot navigate JSON object keys or values. ## openCypher Compatibility Queries must run on both Neo4j and Amazon Neptune. Neptune implements a subset of Cypher, so several convenient constructs are unavailable. Avoid the following: | Feature | Use instead | | - | - | | APOC procedures (`apoc.*`) | Real nodes and relationships in the graph | | Neptune extensions | Standard openCypher | | `any(x IN list ...)` | `size([x IN list WHERE pred]) > 0` | | `all(x IN list ...)` | `size([x IN list WHERE pred]) = size(list)` | | `none(x IN list ...)` | `size([x IN list WHERE pred]) = 0` | | `reduce()` | `UNWIND` plus `collect()` | | `FOREACH` | `WITH` plus `UNWIND` plus `SET` | | Regex `=~` | `toLower()` plus exact match, or `STARTS WITH` / `CONTAINS` | | `CALL () { UNION }` | Multi-label `OR` in `WHERE` | | Carried value plus aggregate expression | Project the aggregate first (`WITH principal_paths, collect(...) AS target_paths`), then combine lists in the next `WITH` | | `EXISTS { MATCH (pattern) WHERE pred }` | Standalone `MATCH (pattern)` plus `WHERE pred`; precede the downstream `collect(path...)` with `WITH DISTINCT ` to dedupe the joins | The carried-value-plus-aggregate rule is worth calling out because it is easy to hit. Neo4j 5.x rejects an expression that concatenates a carried list variable with an aggregate in the same projection: ```cypher theme={null} // Rejected: "Aggregation column contains implicit grouping expressions" WITH principal_paths + collect(DISTINCT path_target) AS paths ``` Split it into two `WITH` clauses so the aggregation resolves before the concatenation: ```cypher theme={null} WITH principal_paths, collect(DISTINCT path_target) AS target_paths WITH principal_paths + target_paths AS paths ``` For list-typed properties in the catalog (action, resource, and so on), traverse the `HAS_*` edges to the child item nodes rather than reading a single field; `split(...)` and comma-string predicates do not apply. ## Best Practices 1. **Chain every MATCH from the account anchor.** An unanchored `MATCH (role:AWSRole)` returns roles from every provider in the graph; `MATCH (aws)--(role:AWSRole)` is scoped. A second-permission `MATCH` such as `MATCH (principal)--(policy2:AWSPolicy)--(stmt2:AWSPolicyStatement)` is safe because `principal` is already bound to the account subgraph. 2. **Pre-aggregate resource lists before matching targets** to avoid Cartesian products (see [Avoiding Cartesian Products](#avoiding-cartesian-products)). 3. **Type the finding probe.** Always `OPTIONAL MATCH (n)-[pfr:HAS_FINDING]-(pf:{PROWLER_FINDING_LABEL} {{status: 'FAIL'}})`. The type lets Neptune apply an inline edge filter; an untyped probe scans every incident edge of high-degree nodes. 4. **Comment each MATCH.** One inline `// ...` line per clause explaining its role. 5. **Never use internal labels.** `_ProviderResource`, `_AWSResource`, `_Tenant_*`, and `_Provider_*` are system isolation labels and must not appear in query text. 6. **Reach the Internet node through path connectivity** with `(internet:Internet)-[:CAN_ACCESS]->(resource)`, never as a standalone match. 7. **Preserve the RETURN contract.** `paths, dpf, dpfr` for the standard shape; add `internet, can_access` for network-exposure queries. The serializer and visualizer depend on these names. ## Naming Conventions * **ID**: kebab-case `{provider}-{category}-{description}`, e.g. `aws-ec2-privesc-passrole-iam`. * **Constant**: `UPPER_SNAKE_CASE` `{PROVIDER}_{CATEGORY}_{DESCRIPTION}`, e.g. `AWS_EC2_PRIVESC_PASSROLE_IAM`. ## Creating a New Query New queries come from one of two input sources: a [pathfinding.cloud](https://github.com/DataDog/pathfinding.cloud) research ID (for example `ECS-001`, `GLUE-001`) or a natural-language description from the requester. The aggregated `paths.json` is too large to fetch whole; query a single path by ID: ```bash theme={null} # Fetch a single path by ID curl -s https://raw.githubusercontent.com/DataDog/pathfinding.cloud/main/docs/paths.json \ | jq '.[] | select(.id == "ecs-002")' # List all path IDs and names curl -s https://raw.githubusercontent.com/DataDog/pathfinding.cloud/main/docs/paths.json \ | jq -r '.[] | "\(.id): \(.name)"' ``` Then follow these steps: 1. **Read the queries module first** to match the existing style: ```text theme={null} api/src/backend/api/attack_paths/queries/ ├── __init__.py ├── types.py # dataclass definitions ├── registry.py └── {provider}.py ``` 2. **Fetch the Cartography schema for the pinned version.** Do not guess labels, properties, or relationships. See [The Graph Model](#the-graph-model). 3. **Build the query** from the canonical template plus the appropriate sub-pattern (privilege escalation or network exposure). Pre-aggregate resource lists, traverse `HAS_*` edges for list-typed properties, and keep the `RETURN` contract. 4. **Register** the constant in the `{PROVIDER}_QUERIES` list at the bottom of the provider file. 5. **Verify compatibility** against the [openCypher Compatibility](#opencypher-compatibility) rules, and confirm the query parses and runs on Neo4j before it reaches Neptune. > [!NOTE] > > AI assistants connected through Prowler MCP Server can fetch the exact Cartography schema for the active scan with the `prowler_get_attack_paths_cartography_schema` tool, which guarantees that generated queries match the schema version pinned by the running Prowler release. ## Reference * **pathfinding.cloud**: [github.com/DataDog/pathfinding.cloud](https://github.com/DataDog/pathfinding.cloud) (use `curl | jq`; the aggregated `paths.json` is too large for a single fetch). * **Cartography AWS schema**: [cartography-cncf.github.io/cartography/modules/aws/schema.html](https://cartography-cncf.github.io/cartography/modules/aws/schema.html). * **Neptune openCypher compliance**: [docs.aws.amazon.com/neptune/latest/userguide/feature-opencypher-compliance.html](https://docs.aws.amazon.com/neptune/latest/userguide/feature-opencypher-compliance.html). * **Neptune openCypher rewrites**: [docs.aws.amazon.com/neptune/latest/userguide/migration-opencypher-rewrites.html](https://docs.aws.amazon.com/neptune/latest/userguide/migration-opencypher-rewrites.html). * **openCypher specification**: [github.com/opencypher/openCypher](https://github.com/opencypher/openCypher). # AWS Provider Source: https://docs.prowler.com/developer-guide/aws-details In this page you can find all the details about [Amazon Web Services (AWS)](https://aws.amazon.com/) provider implementation in Prowler. By default, Prowler will audit just one account and organization settings per scan. To configure it, follow the [AWS getting started guide](/user-guide/providers/aws/getting-started-aws). ## AWS Provider Classes Architecture The AWS provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the AWS-specific implementation, highlighting how the generic provider concepts are realized for AWS in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). In next subsection you can find a list of the main classes of the AWS provider. ### `AwsProvider` (Main Class) * **Location:** [`prowler/providers/aws/aws_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for AWS-specific logic, session management, credential validation, role assumption, region and organization discovery, and configuration. * **Key AWS Responsibilities:** * Initializes and manages AWS sessions (with or without role assumption, MFA, etc.). * Validates credentials and sets up the AWS identity context. * Loads and manages configuration, mutelist, and fixer settings. * Discovers enabled AWS regions and organization metadata. * Provides properties and methods for downstream AWS service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/aws/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/models.py) * **Purpose:** Define structured data for AWS identity, session, credentials, organization info, and more. * **Key AWS Models:** * `AWSOrganizationsInfo`: Holds AWS Organizations metadata, to be used by the checks. * `AWSCredentials`, `AWSAssumeRoleInfo`, `AWSAssumeRoleConfiguration`: Used for role assumption and session management. * `AWSIdentityInfo`: Stores account, user, partition, and region context for the scan. * `AWSSession`: Wraps the current and original [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) sessions and config. ### `AWSService` (Service Base Class) * **Location:** [`prowler/providers/aws/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/lib/service/service.py) * **Purpose:** Abstract base class that all AWS service-specific classes inherit from. This implements the generic service pattern (described in [service page](/developer-guide/services#service-base-class)) specifically for AWS. * **Key AWS Responsibilities:** * Receives an `AwsProvider` instance to access session, identity, and configuration. * Manages clients for all services by regions. * Provides `__threading_call__` method to make boto3 calls in parallel. By default, these calls are made by region, but it can be overridden with the first parameter of the method and use by resource. * Exposes common audit context (`audited_account`, `audited_account_arn`, `audited_partition`, `audited_resources`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/aws/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/exceptions/exceptions.py) * **Purpose:** Custom exception classes for AWS-specific error handling, such as credential and role errors. ### Session and Utility Helpers * **Location:** [`prowler/providers/aws/lib/`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/lib/) * **Purpose:** Helpers for session setup, ARN parsing, mutelist management, and other cross-cutting concerns. ## Specific Patterns in AWS Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the right now implemented services in the following locations: * Directly in the code, in location [`prowler/providers/aws/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/aws/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and taking other services already implemented as reference. In next subsection you can find a list of common patterns that are used across all AWS services. ### AWS Service Common Patterns * Services communicate with AWS using boto3, you can find the documentation with all the services [here](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). * Every AWS service class inherits from `AWSService`, ensuring access to session, identity, configuration, and threading utilities. * The constructor (`__init__`) always calls `super().__init__` with the service name and provider (e.g. `super().__init__(__class__.__name__, provider))`). Ensure that the service name in boto3 is the same that you use in the constructor. Usually is used the `__class__.__name__` to get the service name because it is the same as the class name. * Resource containers **must** be initialized in the constructor. They should be dictionaries, with the key being the resource ARN or equivalent unique identifier and the value being the resource object. * Resource discovery and attribute collection are parallelized using `self.__threading_call__`, typically by region or resource, for performance. The first parameter of the method is the iterator, if not provided, it will be the region; but if present indicate an array of the resources to be processed. * Resource filtering is consistently enforced using `self.audit_resources` attribute and `is_resource_filtered` function, it is used to see if user has provided some resource that is not in the audit scope, so we can skip it in the service logic. Normally it is used before storing the resource in the service container as follows: `if not self.audit_resources or (is_resource_filtered(resource["arn"], self.audit_resources)):`. * All AWS resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * AWS API calls are wrapped in try/except blocks, with specific handling for `ClientError` and generic exceptions, always logging errors. * If ARN is not present for some resource, it can be constructed using string interpolation, always including partition, service, region, account, and resource ID. * Tags and additional attributes that cannot be retrieved from the default call, should be collected and stored for each resource using dedicated methods and threading using the resource object list as iterator. * When accessing dictionary values from AWS API responses, always use `.get()` with a default value instead of direct dictionary access (e.g., `response.get("Policies", {})` instead of `response["Policies"]`). AWS API responses may not always include all keys, and direct access can cause `KeyError` exceptions that break the entire scan for that service. ### Extending an Existing Service with New Attributes When adding a new check that requires data not yet collected by an existing service, you need to extend the service by adding new attributes to its resource models and updating the data collection methods. This is a common contributor task that follows a consistent pattern: 1. **Identify the missing data**: Determine which AWS API call provides the data you need and whether it's already being called by the service. 2. **Add new attributes to the resource model**: Extend the Pydantic `BaseModel` class for the resource with the new fields. Use `Optional` types with `None` as the default value to maintain backward compatibility with existing checks. 3. **Update the data collection method**: Modify the existing method that fetches resource details to also extract and store the new attributes. If no existing method fetches the data, add a new method and call it in the constructor using `self.__threading_call__` if possible. 4. **Use safe dictionary access**: When extracting values from API responses, always use `.get()` with appropriate defaults to prevent `KeyError` exceptions when the API doesn't return certain fields. #### Example: Adding DKIM Status to SES Identities ```python theme={null} # Step 1 & 2: Add new fields to the resource model class Identity(BaseModel): name: str arn: str region: str type: Optional[str] policy: Optional[dict] = None tags: Optional[list] = [] # New attributes for DKIM check dkim_status: Optional[str] = None dkim_signing_attributes_origin: Optional[str] = None # Step 3: Update the data collection method def _get_email_identities(self, identity): try: regional_client = self.regional_clients[identity.region] identity_attributes = regional_client.get_email_identity( EmailIdentity=identity.name ) # Step 4: Use .get() for safe dictionary access for content_key, content_value in identity_attributes.get("Policies", {}).items(): identity.policy = loads(content) identity.tags = identity_attributes.get("Tags", []) # Extract new DKIM attributes identity.dkim_status = identity_attributes.get("DkimStatus") identity.dkim_signing_attributes_origin = ( identity_attributes.get("DkimSigningAttributesOrigin") ) except Exception as error: logger.error( f"{regional_client.region} -- {error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) ``` 5. **Update the service tests**: Add the new attributes to the test mock data and assertions to verify correct data extraction. ## Specific Patterns in AWS Checks The AWS checks pattern is described in [checks page](/developer-guide/checks). You can find all the right now implemented checks: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/aws/services/s3/s3_bucket_acl_prohibited/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/aws/services/s3/s3_bucket_acl_prohibited)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is following the [check creation documentation](/developer-guide/checks#creating-a-check) and taking other similar checks as reference. ### Check Report Class The `Check_Report_AWS` class models a single finding for an AWS resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `Check_Report_AWS` extends the base report structure with AWS-specific fields, enabling detailed tracking of the resource, ARN, and region associated with each finding. #### Constructor and Attribute Population When you instantiate `Check_Report_AWS`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its AWS-specific attributes from the resource, using the following logic (in order of precedence): * **`resource_id`**: * Uses `resource.id` if present. * Otherwise, uses `resource.name` if present. * Defaults to an empty string if none are available. * **`resource_arn`**: * Uses `resource.arn` if present. * Defaults to an empty string if ARN is not present in the resource object. * **`region`**: * Uses `resource.region` if present. * Defaults to an empty string if region is not present in the resource object. If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from those you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} report = Check_Report_AWS( metadata=check_metadata, resource=resource_object ) report.status = "PASS" report.status_extended = "Resource is compliant." ``` # Azure Provider Source: https://docs.prowler.com/developer-guide/azure-details In this page you can find all the details about [Microsoft Azure](https://azure.microsoft.com/) provider implementation in Prowler. By default, Prowler will audit all the subscriptions that it is able to list in the Microsoft Entra tenant, and tenant Entra ID service. To configure it, follow the [Azure getting started guide](/user-guide/providers/azure/getting-started-azure). ## Azure Provider Classes Architecture The Azure provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the Azure-specific implementation, highlighting how the generic provider concepts are realized for Azure in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). In next subsection you can find a list of the main classes of the Azure provider. ### `AzureProvider` (Main Class) * **Location:** [`prowler/providers/azure/azure_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/azure_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for Azure-specific logic, session management, credential validation, and configuration. * **Key Azure Responsibilities:** * Initializes and manages Azure sessions (supports Service Principal, CLI, Browser, and Managed Identity authentication). * Validates credentials and sets up the Azure identity context. * Loads and manages configuration, mutelist, and fixer settings. * Retrieves subscription(s) metadata. * Provides properties and methods for downstream Azure service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/azure/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/models.py) * **Purpose:** Define structured data for Azure identity, session, region configuration, and subscription info. * **Key Azure Models:** * `AzureIdentityInfo`: Holds Azure identity metadata, including tenant ID, domain, subscription names and IDs, and locations. * `AzureRegionConfig`: Stores the specific region that will be audited. That can be: Global, US Government or China. * `AzureSubscription`: Represents a subscription with ID, display name, and state. ### `AzureService` (Service Base Class) * **Location:** [`prowler/providers/azure/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/lib/service/service.py) * **Purpose:** Abstract base class that all Azure service-specific classes inherit from. This implements the generic service pattern (described in [service page](/developer-guide/services#service-base-class)) specifically for Azure. * **Key Azure Responsibilities:** * Receives an `AzureProvider` instance to access session, identity, and configuration. * Manages clients for all services by subscription. * Exposes common audit context (`subscriptions`, `locations`, `audit_config`, `fixer_config`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/azure/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/exceptions/exceptions.py) * **Purpose:** Custom exception classes for Azure-specific error handling, such as credential, region, and session errors. ### Session and Utility Helpers * **Location:** [`prowler/providers/azure/lib/`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/lib/) * **Purpose:** Helpers for argument parsing, region setup, mutelist management, and other cross-cutting concerns. ## Specific Patterns in Azure Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/azure/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/azure/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and taking other services already implemented as reference. In next subsection you can find a list of common patterns that are used across all Azure services. ### Azure Service Common Patterns * Services communicate with Azure using the Azure Python SDK, mainly using the Azure Management Client (except for the Microsoft Entra ID service, that is using the Microsoft Graph API), you can find the documentation with all the management services [here](https://learn.microsoft.com/en-us/python/api/overview/azure/?view=azure-python). * Every Azure service class inherits from `AzureService`, ensuring access to session, identity, configuration, and client utilities. * The constructor (`__init__`) always calls `super().__init__` with the service Azure Management Client and Prowler provider object (e.g `super().__init__(WebSiteManagementClient, provider)`). * Resource containers **must** be initialized in the constructor, and they should be dictionaries, with the key being the subscription ID, the value being a dictionary with the resource ID as key and the resource object as value. * All Azure resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. Some are represented as dataclasses due to legacy reasons, but new resources should be represented as Pydantic `BaseModel` classes. * Azure SDK functions are wrapped in try/except blocks, with specific handling for errors, always logging errors. It is a best practice to create a custom function for every Azure SDK call, in that way we can handle the errors in a more specific way. ## Specific Patterns in Azure Checks The Azure checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/azure/services/storage/storage_blob_public_access_level_is_disabled/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/azure/services/storage/storage_blob_public_access_level_is_disabled)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is the [Azure check implementation documentation](/developer-guide/checks#creating-a-check) and taking other similar checks as reference. ### Check Report Class The `Check_Report_Azure` class models a single finding for an Azure resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `Check_Report_Azure` extends the base report structure with Azure-specific fields, enabling detailed tracking of the resource, resource ID, name, subscription, and location associated with each finding. #### Constructor and Attribute Population When you instantiate `Check_Report_Azure`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its Azure-specific attributes from the resource, using the following logic (in order of precedence): * **`resource_id`**: * Uses `resource.id` if present. * Otherwise, uses `resource.resource_id` if present. * Defaults to an empty string if not available. * **`resource_name`**: * Uses `resource.name` if present. * Otherwise, uses `resource.resource_name` if present. * Defaults to an empty string if not available. * **`subscription`**: * Defaults to an empty string, it **must** be set in the check logic. * **`location`**: * Uses `resource.location` if present. * Defaults to an empty string if not available. If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from which you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} report = Check_Report_Azure( metadata=check_metadata, resource=resource_object ) report.subscription = subscription_id report.status = "PASS" report.status_extended = "Resource is compliant." ``` # Check Metadata Guidelines Source: https://docs.prowler.com/developer-guide/check-metadata-guidelines ## Introduction This guide provides comprehensive guidelines for creating check metadata in Prowler. For basic information on check metadata structure, refer to the [check metadata](/developer-guide/checks#metadata-structure-for-prowler-checks) section. ## Check Title Guidelines ### Writing Guidelines 1. **Determine Resource Finding Scope (Singular vs. Plural)**: When determining whether to use singular or plural in the check title, examine the code for certain patterns. If the code contains a loop that generates an individual report for each resource, use the singular form. If the code produces a single report that covers all resources collectively, use the plural form. For organization- or account-wide checks, select the scope that best matches the breadth of the evaluation. Additionally, review the `status_extended` field messages in the code, as they often provide clues about whether the check is scoped to individual resources or to groups of resources. Analyze the detection code to determine if the check reports on individual resources or aggregated resources: * **Singular**: Use when the check creates one report per resource (e.g., "EC2 instance has IMDSv2 enforced", "S3 bucket does not allow public write access"). * **Plural**: Use when the check creates one report for all resources together (e.g., "All EC2 instances have IMDSv2 enforced", "S3 buckets do not allow public write access"). 2. **Describe the Compliant (*PASS*) State**: Always write the title to describe the **desired, compliant state** of the resources. The title should reflect what it looks like when the audited resource is following the check's requirements. 3. **Be Specific and Factual**: Include the exact secure configuration being verified. Avoid vague or generic terms like "properly configured". 4. **Avoid Redundant or Action Words**: Do not include verbs like "Check", "Verify", "Ensure", or "Monitor". The title is a declarative statement of the secure condition. 5. **Length Limit**: Keep the title under 150 characters. ### Common Mistakes to Avoid * Starting with verbs like "Check", "Verify", "Ensure", "Make sure". Always start with the affected resource instead. * Being too vague or generic (e.g., "Ensure security groups are properly configured", what does it mean? "properly configured" is not a clear description of the compliant state). * Focusing on the non-compliant state instead of the compliant state. * Using unclear scope and resource identification. ## Check Type Guidelines (AWS Only) ### AWS Security Hub Type Format AWS Security Hub uses a three-part type taxonomy: * **Namespace**: The top-level security domain. * **Category**: The security control family or area. * **Classifier**: The specific security concern (optional). A partial path may be defined (e.g., `TTPs` or `TTPs/Defense Evasion` are valid). ### Selection Guidelines 1. **Be Specific**: Use the most specific classifier that accurately describes the check. 2. **Standard Compliance**: Consider if the check relates to specific compliance standards. 3. **Multiple Types**: You can specify multiple types if the check addresses multiple concerns. ## Description Guidelines ### Writing Guidelines 1. **Focus on the Finding**: All fields should address how the finding affects the security posture, rather than the control itself. 2. **Use Natural Language**: Write in simple, clear paragraphs with complete, grammatically correct sentences. 3. **Use Markdown Formatting**: Enhance readability with: * Use **bold** for emphasis on key security concepts. * Use *italic* for a secondary emphasis. Use it for clarifications, conditions, or optional notes. But don't abuse it. * Use `code` formatting for specific configuration values, or technical details. Don't use it for service names or common technical terms. * Use one or two line breaks (`\n` or `\n\n`) to separate distinct ideas. * Use bullet points (`-`) for listing multiple concepts or actions. * Use numbers for listing steps or sequential actions. 4. **Be Concise**: Maximum 400 characters (spaces count). Every word should add value. 5. **Explain What the Finding Means**: Focus on what the security control evaluates and what it means when it passes or fails, but without explicitly stating the pass or fail state. 6. **Be Technical but Clear**: Use appropriate technical terminology while remaining understandable. 7. **Avoid Risk Descriptions**: Do not describe potential risks, threats, or consequences. 8. **CheckTitle and Description can be the same**: If the check is very simple and the title is already clear, you can use the same text for the description. ### Common Mistakes to Avoid * **Technical Implementation Details**: "The control loops through all instances and calls the describe\_instances API...". * **Vague Descriptions**: "This control verifies proper configuration of resources". What does it mean? "proper configuration" is not a clear description of the compliant state. * **Risk Descriptions**: "This could lead to data breaches" or "This poses a security threat". * **Starting with Verbs**: "Check if...", "Verify...", "Ensure...". Always start with the affected resource instead. * **References to Pass/Fail States**: Avoid using words like "pass" or "fail". ## Risk Guidelines ### Writing Guidelines 1. **Explain the Cybersecurity Impact**: Focus on how the finding affects confidentiality, integrity, or availability (CIA triad). If the CIA triad does not apply, explain the risk in terms of the organization's business objectives. 2. **Be Specific About Threats**: Clearly state what could happen if this security control is not in place. What attacks or incidents become possible? 3. **Focus on Risk Context**: Explain the specific security implications of the finding, not just generic security risks. 4. **Use Markdown Formatting**: Enhance readability with markdown formatting: * Use **bold** for emphasis on key security concepts. * Use *italic* for a secondary emphasis. Use it for clarifications, conditions, or optional notes. But don't abuse it. * Use `code` formatting for specific configuration values, or technical details. Don't use it for service names or common technical terms. * Use one or two line breaks (`\n` or `\n\n`) to separate distinct ideas. * Use bullet points (`-`) for listing multiple concepts or actions. * Use numbers for listing steps or sequential actions. 5. **Be Concise**: Maximum 400 characters. Make every word count. ### Common Mistakes to Avoid * **Generic Risks**: "This could lead to security issues" or "Regulatory compliance violations". * **Technical Implementation Focus**: "The API call might fail and return incorrect results...". * **Overly Broad Statements**: "This is a serious security risk that could impact everything". * **Vague Threats**: "This could be exploited by threat actors" without explaining how. ## Recommendation Guidelines ### Writing Guidelines 1. **Provide Actionable Best Practice Guidance**: Explain what should be done to maintain security posture. Focus on preventive measures and proactive security practices. 2. **Be Principle-Based**: Reference established security principles (least privilege, defense in depth, zero trust, separation of duties) where applicable. 3. **Focus on Prevention**: Explain best practices that prevent the security issue from occurring, not just detection or remediation. 4. **Use Markdown Formatting**: Enhance readability with markdown formatting: * Use **bold** for emphasis on key security concepts. * Use *italic* for a secondary emphasis. Use it for clarifications, conditions, or optional notes. But don't abuse it. * Use `code` formatting for specific configuration values, or technical details. Don't use it for service names or common technical terms. * Use one or two line breaks (`\n` or `\n\n`) to separate distinct ideas. * Use bullet points (`-`) for listing multiple concepts or actions. * Use numbers for listing steps or sequential actions. 5. **Be Concise**: Maximum 400 characters. ### Common Mistakes to Avoid * **Specific Remediation Steps**: "1. Go to the console\n2. Click on settings..." - Focus on principles, not click-by-click instructions. * **Implementation Details**: "Configure the JSON policy with the following IAM actions..." - Explain what to achieve, not how. * **Vague Guidance**: "Follow security best practices..." without explaining what those practices are. * **Resource-Specific Recommendations**: "Enable MFA on user [john.doe@example.com](mailto:john.doe@example.com)" - Keep it general. * **Missing Context**: Not explaining why the best practice is important for security. ### Good Examples * *"Avoid exposing sensitive resources directly to the Internet; configure access controls to limit exposure."* * *"Apply the principle of least privilege when assigning permissions to users and services."* * *"Regularly review and update your security configurations to align with current best practices."* ## Remediation Code Guidelines ### Critical Requirement The **fundamental principle** is to focus on the **specific change** that converts the finding from non-compliant to compliant. Also is important to keep all code examples as short as possible, including the essential code to fix the issue. Remove any extra configuration, optional parameters, or nice-to-have settings and add comments to explain the code when possible. ### Common Guidelines for All Code Fields 1. **Be Minimal**: Keep code blocks as short as possible - only include what is absolutely necessary. 2. **Focus on the Fix**: Remove any extra configuration, optional parameters, or nice-to-have settings. 3. **Be Accurate**: Ensure all commands and code are syntactically correct. 4. **Use Markdown Formatting**: Format code properly using code blocks and appropriate syntax highlighting. 5. **Follow Best Practices**: Use the most secure and recommended approaches for each platform. ### CLI Guidelines * Only provide a single command that directly changes the finding from fail to pass. * The command must be executable as-is and resolve the security issue completely. * Use proper command syntax for the provider (AWS CLI, Azure CLI, gcloud, kubectl, etc.). * Do not use markdown formatting or code blocks - just the raw command. * Do not include multiple commands, comments, or explanations. * If the issue cannot be resolved with a single command, leave this field empty. ### Native IaC Guidelines * **Keep It Minimal**: Only include the specific resource/configuration that fixes the security issue. * Format as markdown code blocks with proper syntax highlighting. * Include only the required properties to fix the issue. * Add comments indicating the critical line(s) that remediate the check. * Use `example_resource` as the generic name for all resources and IDs. ### Terraform Guidelines * **Keep It Minimal**: Only include the specific resource/configuration that fixes the security issue. * Provide valid HCL (HashiCorp Configuration Language) code with an example of a compliant configuration. * Use the latest Terraform syntax and provider versions. * Include only the required arguments to fix the issue - skip optional parameters. * Format as markdown code blocks with `hcl` syntax highlighting. * Add comments indicating the critical line(s) that remediate the check. * Use `example_resource` as the generic name for all resources and IDs. * Skip provider requirements unless critical for the fix. ### Other (Manual Steps) Guidelines * **Keep It Minimal**: Only include the exact steps needed to fix the security issue. * Provide step-by-step instructions for manual remediation through web interfaces. * Use numbered lists for sequential steps. * Be specific about menu locations, button names, and settings. * Skip optional configurations or nice-to-have settings. * Format using markdown for better readability. ## Categories Guidelines ### Selection Guidelines 1. **Be Specific**: Only select categories that directly relate to what the automated control evaluates. 2. **Primary Focus**: Consider the primary security concern the automated control addresses. 3. **Avoid Over-Categorization**: Do not select categories just because they are tangentially related. ### Available Categories | Category | Definition | | - | - | | encryption | Ensures data is encrypted in transit and/or at rest, including key management practices | | internet-exposed | Checks that limit or flag public access to services, APIs, or assets from the Internet | | logging | Ensures appropriate logging of events, activities, and system interactions for traceability | | secrets | Manages and protects credentials, API keys, tokens, and other sensitive information | | resilience | Ensures systems can maintain availability and recover from disruptions, failures, or degradation. Includes redundancy, fault-tolerance, auto-scaling, backup, disaster recovery, and failover strategies | | threat-detection | Identifies suspicious activity or behaviors using IDS, malware scanning, or anomaly detection | | trust-boundaries | Enforces isolation or segmentation between different trust levels (e.g., VPCs, tenants, network zones) | | vulnerabilities | Detects or remediates known software, infrastructure, or config vulnerabilities (e.g., CVEs) | | cluster-security | Secures Kubernetes cluster components such as API server, etcd, and role-based access | | container-security | Ensures container images and runtimes follow security best practices | | node-security | Secures nodes running containers or services | | gen-ai | Checks related to safe and secure use of generative AI services or models | | ci-cd | Ensures secure configurations in CI/CD pipelines | | identity-access | Governs user and service identities, including least privilege, MFA, and permission boundaries | | email-security | Ensures detection and protection against phishing, spam, spoofing, etc. | | forensics-ready | Ensures systems are instrumented to support post-incident investigations. Any digital trace or evidence (logs, volume snapshots, memory dumps, network captures, etc.) preserved immutably and accompanied by integrity guarantees, which can be used in a forensic analysis | | software-supply-chain | Detects or prevents tampering, unauthorized packages, or third-party risks in software supply chain | | e3 | M365 and Azure Entra checks enabled by or dependent on an E3 license (e.g., baseline security policies, conditional access) | | e5 | M365 and Azure Entra checks enabled by or dependent on an E5 license (e.g., advanced threat protection, audit, DLP, and eDiscovery) | | privilege-escalation | Detects IAM policies or permissions that allow identities to elevate their privileges beyond their intended scope, potentially gaining administrator or higher-level access through specific action combinations | | ec2-imdsv1 | Identifies EC2 instances using Instance Metadata Service version 1 (IMDSv1), which is vulnerable to SSRF attacks and should be replaced with IMDSv2 for enhanced security | | vercel-hobby-plan | Vercel checks whose audited feature is available on the Hobby plan (and therefore also on Pro and Enterprise plans) | | vercel-pro-plan | Vercel checks whose audited feature requires a Pro plan or higher, including features also available on Enterprise or via supported paid add-ons for Pro plans | | vercel-enterprise-plan | Vercel checks whose audited feature requires the Enterprise plan | # Prowler Checks Source: https://docs.prowler.com/developer-guide/checks This guide explains how to create new checks in Prowler. ## Introduction Checks are the core component of Prowler. A check is a piece of code designed to validate whether a configuration aligns with cybersecurity best practices. Execution of a check yields a finding, which includes the result and contextual metadata (e.g., outcome, risks, remediation). ### Creating a Check The most common high level steps to create a new check are: 1. Prerequisites: * Verify the check does not already exist by searching [Prowler Hub](https://hub.prowler.com) or checking `prowler/providers//services///`. * Ensure required provider and service exist. If not, follow the [Provider](/developer-guide/provider) and [Service](/developer-guide/services) documentation to create them. * Confirm the service has implemented all required methods and attributes for the check (in most cases, you will need to add or modify some methods in the service to get the data you need for the check). 2. Navigate to the service directory. The path should be as follows: `prowler/providers//services/`. 3. Create a check-specific folder. The path should follow this pattern: `prowler/providers//services//`. Adhere to the [Naming Format for Checks](#naming-format-for-checks). 4. Populate the folder with files as specified in [File Creation](#file-creation). 5. Run the check locally to ensure it works as expected. For checking you can use the CLI in the next way: * To ensure the check has been detected by Prowler: `uv run python prowler-cli.py --list-checks | grep `. * To run the check, to find possible issues: `uv run python prowler-cli.py --log-level ERROR --verbose --check `. 6. Create comprehensive tests for the check that cover multiple scenarios including both PASS (compliant) and FAIL (non-compliant) cases. For detailed information about test structure and implementation guidelines, refer to the [Testing](/developer-guide/unit-testing) documentation. 7. If the check and its corresponding tests are working as expected, you can submit a PR to Prowler. ### Naming Format for Checks If you already know the check name when creating a request or implementing a check, use a descriptive identifier with lowercase letters and underscores only. Recommended patterns: * `__` The name components are: * `service` – The main service or product area being audited (e.g., ec2, entra, iam, bedrock). * `resource` – The resource, feature, or configuration being evaluated. It can be a single word or a compound phrase joined with underscores (e.g., instance, policy, guardrail, sensitive\_information\_filter). * `best_practice` – The expected secure state or best practice being checked (e.g., enabled, encrypted, restricted, configured, not\_publicly\_accessible). Additional guidance: * Use underscores only. Do not use hyphens. * Keep the name specific enough to describe the behavior of the check. * The first segment should match the service or product area whenever possible. Examples: * `s3_bucket_versioning_enabled` * `bedrock_guardrail_sensitive_information_filter_enabled` ### File Creation Each check in Prowler follows a straightforward structure. Within the newly created folder, three files must be added to implement the check logic: * `__init__.py` (empty file) – Ensures Python treats the check folder as a package. * `.py` (code file) – Contains the check logic, following the prescribed format. Please refer to the [prowler's check code structure](/developer-guide/checks#prowlers-check-code-structure) for more information. * `.metadata.json` (metadata file) – Defines the check's metadata for contextual information. Please refer to the [check metadata](/developer-guide/checks#metadata-structure-for-prowler-checks) for more information. ## Prowler's Check Code Structure Prowler's check structure is designed for clarity and maintainability. It follows a dynamic loading approach based on predefined paths, ensuring seamless integration of new checks into a provider's service without additional manual steps. Below the code for a generic check is presented. It is strongly recommended to consult other checks from the same provider and service to understand provider-specific details and patterns. This will help ensure consistency and proper implementation of provider-specific requirements. Report fields are the most dependent on the provider, consult the `CheckReport` class for more information on what can be included in the report [here](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py). > [!NOTE] > > Legacy providers (AWS, Azure, GCP, Kubernetes) follow the `Check_Report_` naming convention. This is not recommended for current instances. Newer providers adopt the `CheckReport` naming convention. Learn more at [Prowler Code](https://github.com/prowler-cloud/prowler/tree/master/prowler/lib/check/models.py). ```python title="Generic Check Class" theme={null} # Required Imports # Import the base Check class and the provider-specific CheckReport class from prowler.lib.check.models import Check, CheckReport # Import the provider service client from prowler.providers..services.._client import _client # Defining the Check Class # Each check must be implemented as a Python class with the same name as its corresponding file. # The class must inherit from the Check base class. class (Check): """ Ensure that meets . This check evaluates whether to ensure . - PASS: . - FAIL: . """ def execute(self): """Execute the check logic. Returns: A list of reports containing the result of the check. """ findings = [] # Iterate over the target resources using the provider service client for resource in _client.: # Initialize the provider-specific report class, passing metadata and resource report = Check_Report_(metadata=self.metadata(), resource=resource) # Set required fields and implement check logic report.status = "PASS" report.status_extended = f"" # If some of the information needed for the report is not inside the resource, it can be set it manually here. # This depends on the provider and the resource that is being audited. # report.region = resource.region # report.resource_tags = getattr(resource, "tags", []) # ... # Example check logic (replace with actual logic): if : report.status = "FAIL" report.status_extended = f"" findings.append(report) return findings ``` ### Data Requirements for Checks in Prowler One of the most important aspects when creating a new check is ensuring that all required data is available from the service client. Often, default API calls are insufficient. Extending the service class with new methods or resource attributes may be required to fetch and store requisite data. ### Statuses for Checks in Prowler Required Fields: status and status\_extended Each check **must** populate the `report.status` and `report.status_extended` fields according to the following criteria: * Status field: `report.status` * `PASS` – Assigned when the check confirms compliance with the configured value. * `FAIL` – Assigned when the check detects non-compliance with the configured value. * `MANUAL` – This status must not be used unless manual verification is necessary to determine whether the status (`report.status`) passes (`PASS`) or fails (`FAIL`). This includes the case where Prowler could not retrieve the data needed to evaluate the resource (see below). * Status extended field: `report.status_extended` * It **must** end with a period (`.`). * It **must** include the audited service, the resource, and a concise explanation of the check result, for instance: `EC2 AMI ami-0123456789 is not public.`. ### Permission and Data-Availability Errors Are Not Findings A `FAIL` must only be emitted when an insecure condition has actually been detected. A check **must never** report `FAIL` because the underlying API call failed: missing permissions or scopes on the scanning identity, an API that is not enabled, a feature that is not licensed, or data that could not be retrieved are scan-configuration problems, not security issues. Reporting them as `FAIL` surfaces a misleading (and often high-severity) finding to the user and skews compliance scores. When the service layer cannot obtain the data a check depends on, the check must: 1. Emit a single `MANUAL` finding scoped to the widest affected resource (the tenant, account, project or subscription), not one finding per resource. For example, if user registration details cannot be read, emit one tenant-level `MANUAL` instead of one per user. 2. Explain in `status_extended` that the check could not be evaluated and what to fix, naming the permission, scope, API or license required, for instance: `Cannot evaluate credential exposure for privileged users: unable to query Microsoft Defender XDR Advanced Hunting. Verify that the ThreatHunting.Read.All permission is granted to the scanning application.` 3. Leave the check's severity untouched. Do not override `report.check_metadata.Severity` to hide the problem. The service layer must make the distinction possible: log the error and expose it to checks in a way that cannot be confused with a legitimate empty result. Common patterns already used in Prowler are: * Defaulting the attribute to `None` (data could not be read) instead of `[]`/`{}` (data was read and is empty), e.g. the `metric_filters is not None` guard in `prowler/providers/aws/services/cloudwatch/lib/metric_filters.py`. * Keeping an availability flag raised on any denied listing, e.g. `logs_client.metric_filters_unavailable` consumed by the AWS CloudWatch metric filter checks. * Keeping an error flag or message next to the data, e.g. `entra_client.user_registration_details_error` in M365 or `*_scan_errors` in AWS Bedrock. * Keeping a set of resources whose lookup failed, e.g. `accessapproval_client.settings_lookup_failed` in GCP. Make sure the error branch only captures real access errors. A `404`/not-found response frequently means the feature is simply not configured, which **is** a legitimate `FAIL`; a `403` or an unexpected exception is not. An "API not enabled" error is usually a scan-configuration problem too — **except** when the API's activation is itself the control being audited (e.g. GCP Access Approval: with `accessapproval.googleapis.com` disabled the feature provably cannot be enabled, so a definitive API-disabled state is a legitimate `FAIL`, while an undetermined state stays `MANUAL`). ```python theme={null} if _client. is None: report = CheckReport(metadata=self.metadata(), resource={}) report.resource_name = "" report.resource_id = "" report.status = "MANUAL" report.status_extended = "Cannot evaluate : could not be retrieved. Verify that is granted to the scanning identity." findings.append(report) return findings ``` ### Prowler's Check Severity Levels The severity of each check is defined in the metadata file using the `Severity` field. Severity values are always lowercase and must be one of the predefined categories below. * `critical` – Highest potential impact with broad exposure that could affect core security boundaries or business operations. * `high` – Substantial potential impact with significant exposure that could affect important security controls or resources. * `medium` – Moderate potential impact with limited exposure that weakens defense layers but has contained scope. * `low` – Minimal potential impact with negligible exposure that represents minor gaps in security posture. * `informational` – Provides valuable information but does not affect the security posture. If the check involves multiple scenarios that may alter its severity, adjustments can be made dynamically within the check's logic using the severity `report.check_metadata.Severity` attribute: ```python theme={null} if : report.status = "PASS" report.check_metadata.Severity = "informational" report.status_extended = f" is compliant with ." elif : report.status = "FAIL" report.check_metadata.Severity = "low" report.status_extended = f" is not compliant with : ." elif : report.status = "FAIL" report.check_metadata.Severity = "medium" report.status_extended = f" is not compliant with : ." elif : report.status = "FAIL" report.check_metadata.Severity = "high" report.status_extended = f" is not compliant with : ." else: report.status = "FAIL" report.check_metadata.Severity = "critical" report.status_extended = f" is not compliant with : ." ``` ### Resource Identification in Prowler Each check **must** populate the report with a unique identifier for the audited resource. This identifier or identifiers are going to depend on the provider and the resource that is being audited. Here are the criteria for each provider: * AWS * Amazon Resource ID — `report.resource_id`. * The resource identifier. This is the name of the resource, the ID of the resource, or a resource path. Some resource identifiers include a parent resource (sub-resource-type/parent-resource/sub-resource) or a qualifier such as a version (resource-type:resource-name:qualifier). * If the resource ID cannot be retrieved directly from the audited resource, it can be extracted from the ARN. It is the last part of the ARN after the last slash (`/`) or colon (`:`). * If no actual resource to audit exists, this format can be used: `/unknown` * Amazon Resource Name — `report.resource_arn`. * The [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) of the audited entity. * If the ARN cannot be retrieved directly from the audited resource, construct a valid ARN using the `resource_id` component as the audited entity. Examples: * Bedrock — `arn::bedrock:::model-invocation-logging`. * DirectConnect — `arn::directconnect:::dxcon`. * If no actual resource to audit exists, this format can be used: `arn:::::/unknown`. * Examples: * AWS Security Hub — `arn::security-hub:::hub/unknown`. * Access Analyzer — `arn::access-analyzer:::analyzer/unknown`. * GuardDuty — `arn::guardduty:::detector/unknown`. * GCP * Resource ID — `report.resource_id`. * Resource ID represents the full, [unambiguous path to a resource](https://google.aip.dev/122#full-resource-names), known as the full resource name. Typically, it follows the format: `//{api_service/resource_path}`. * If the resource ID cannot be retrieved directly from the audited resource, by default the resource name is used. * Resource Name — `report.resource_name`. * Resource Name usually refers to the name of a resource within its service. * Azure * Resource ID — `report.resource_id`. * Resource ID represents the full Azure Resource Manager path to a resource, which follows the format: `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}`. * Resource Name — `report.resource_name`. * Resource Name usually refers to the name of a resource within its service. * If the [resource name](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) cannot be retrieved directly from the audited resource, the last part of the resource ID can be used. * Kubernetes * Resource ID — `report.resource_id`. * The UID of the Kubernetes object. This is a system-generated string that uniquely identifies the object within the cluster for its entire lifetime. See [Kubernetes Object Names and IDs - UIDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids). * Resource Name — `report.resource_name`. * The name of the Kubernetes object. This is a client-provided string that must be unique for the resource type within a namespace (for namespaced resources) or cluster (for cluster-scoped resources). Names typically follow DNS subdomain or label conventions. See [Kubernetes Object Names and IDs - Names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). * M365 * Resource ID — `report.resource_id`. * If the audited resource has a globally unique identifier such as a `guid`, use it as the `resource_id`. * If no `guid` exists, use another unique and relevant identifier for the resource, such as the tenant domain, the internal policy ID, or a representative string following the format `/`. * Resource Name — `report.resource_name`. * Use the visible or descriptive name of the audited resource. If no explicit name is available, use a clear description of the resource or configuration being evaluated. * Examples: * For an organization: * `resource_id`: Organization GUID * `resource_name`: Organization name * For a policy: * `resource_id`: Unique policy ID * `resource_name`: Policy display name * For global configurations: * `resource_id`: Tenant domain or representative string (e.g., "userSettings") * `resource_name`: Description of the configuration (e.g., "SharePoint Settings") * GitHub * Resource ID — `report.resource_id`. * The ID of the GitHub resource. This is a system-generated integer that uniquely identifies the resource within the GitHub platform. * Resource Name — `report.resource_name`. * The name of the GitHub resource. In the case of a repository, this is just the repository name. For full repository names use the resource `full_name`. ### Configurable Checks in Prowler See [Configurable Checks](/developer-guide/configurable-checks) for detailed information on making checks configurable using the `audit_config` object and configuration file. ## Metadata Structure for Prowler Checks Each Prowler check must include a metadata file named `.metadata.json` that must be located in its directory. This file supplies crucial information for execution, reporting, and context. ### Example Metadata File Below is a generic example of a check metadata file. **Do not include comments in actual JSON files.** ````json theme={null} { "Provider": "aws", "CheckID": "service_resource_security_setting", "CheckTitle": "Service resource has security setting enabled", "CheckType": [], "ServiceName": "service", "SubServiceName": "", "ResourceIdTemplate": "", "Severity": "medium", "ResourceType": "Other", "ResourceGroup": "security", "Description": "This check verifies that the service resource has the required **security setting** enabled to protect against potential vulnerabilities.\n\nIt ensures that the resource follows security best practices and maintains proper access controls. The check evaluates whether the security configuration is properly implemented and active.", "Risk": "Without proper security settings, the resource may be vulnerable to:\n\n- **Unauthorized access** - Malicious actors could gain entry\n- **Data breaches** - Sensitive information could be compromised\n- **Security threats** - Various attack vectors could be exploited\n\nThis could result in compliance violations and potential financial or reputational damage.", "RelatedUrl": "", "AdditionalURLs": ["https://example.com/security-documentation", "https://example.com/best-practices"], "Remediation": { "Code": { "CLI": "provider-cli service enable-security-setting --resource-id resource-123", "NativeIaC": "```yaml\nType: Provider::Service::Resource\nProperties:\n SecuritySetting: enabled\n ResourceId: resource-123\n```", "Other": "1. Open the provider management console\n2. Navigate to the service section\n3. Select the resource\n4. Enable the security setting\n5. Save the configuration", "Terraform": "```hcl\nresource \"provider_service_resource\" \"example\" {\n resource_id = \"resource-123\"\n security_setting = true\n}\n```" }, "Recommendation": { "Text": "Enable security settings on all service resources to ensure proper protection. Regularly review and update security configurations to align with current best practices.", "Url": "https://hub.prowler.com/check/service_resource_security_setting" } }, "Categories": ["internet-exposed", "secrets"], "DependsOn": [], "RelatedTo": ["service_resource_security_setting", "service_resource_security_setting_2"], "Notes": "This is a generic example check that should be customized for specific provider and service requirements." } ```` ### Metadata Fields and Their Purpose #### Provider The Prowler provider related to the check. The name **must** be lowercase and match the provider folder name. For supported providers refer to [Prowler Hub](https://hub.prowler.com/check) or directly to [Prowler Code](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers). #### CheckID The unique identifier for the check inside the provider. This field **must** match the check's folder, Python file, and JSON metadata file name. For more information about naming, refer to the [Naming Format for Checks](#naming-format-for-checks) section. #### CheckTitle The `CheckTitle` field must be plain text, clearly and succinctly define **the best practice being evaluated and which resource(s) each finding applies to**. The title should be specific, concise (no more than 150 characters), and reference the relevant resource(s) involved. **Always write the `CheckTitle` to describe the *PASS* case**, the desired secure or compliant state of the resource(s). This helps ensure that findings are easy to interpret and that the title always reflects the best practice being met. For detailed guidelines on writing effective check titles, including how to determine singular vs. plural scope and common mistakes to avoid, see [Check Title Guidelines](/developer-guide/check-metadata-guidelines#check-title-guidelines). #### CheckType > [!WARNING] > > This field is only applicable to the AWS provider. It follows the [AWS Security Hub Types](https://docs.aws.amazon.com/securityhub/latest/userguide/asff-required-attributes.html#Types) format using the pattern `namespace/category/classifier`. For the complete AWS Security Hub selection guidelines, see [Check Type Guidelines](/developer-guide/check-metadata-guidelines#check-type-guidelines-aws-only). #### ServiceName The name of the provider service being audited. Must be lowercase and match the service folder name. For supported services refer to [Prowler Hub](https://hub.prowler.com/check) or the [Prowler Code](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers). #### SubServiceName This field is in the process of being deprecated and should be **left empty**. #### ResourceIdTemplate This field is in the process of being deprecated and should be **left empty**. #### Severity Severity level if the check fails. Must be one of: `critical`, `high`, `medium`, `low`, or `informational`, and written in lowercase. See [Prowler's Check Severity Levels](#prowlers-check-severity-levels) for details. #### ResourceType The type of resource being audited. This field helps categorize and organize findings by resource type for better analysis and reporting. For each provider: * **AWS**: Use [Security Hub resource types](https://docs.aws.amazon.com/securityhub/latest/userguide/asff-resources.html) or PascalCase CloudFormation types removing the `::` separator used in CloudFormation templates (e.g., in CloudFormation template the type of an EC2 instance is `AWS::EC2::Instance` but in the check it should be `AwsEc2Instance`). Use `Other` if none apply. * **Azure**: Use types from [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/reference/supported-tables-resources), for example: `Microsoft.Storage/storageAccounts`. * **Google Cloud**: Use [Cloud Asset Inventory asset types](https://cloud.google.com/asset-inventory/docs/asset-types), for example: `compute.googleapis.com/Instance`. * **Kubernetes**: Use types shown under `KIND` from `kubectl api-resources`. * **Oracle Cloud Infrastructure**: Use types from [Oracle Cloud Infrastructure documentation](https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/Content/Search/Tasks/queryingresources_topic-Listing_Supported_Resource_Types.htm). * **OpenStack**: Use types from [OpenStack Heat resource types](https://docs.openstack.org/heat/latest/template_guide/openstack.html). * **Alibaba Cloud**: Use types from [Alibaba Cloud ROS resource types](https://www.alibabacloud.com/help/en/ros/developer-reference/list-of-resource-types-by-service). * **Any other provider**: Use `NotDefined` due to lack of standardized resource types in their SDK or documentation. #### ResourceGroup A high-level classification that groups checks by the type of cloud resource they audit. This field enables filtering and organizing findings by resource category across all providers. The value must be one of the following predefined groups: | Group | Description | | - | - | | `compute` | Virtual machines, instances, auto-scaling groups, workspaces, streaming | | `container` | Container orchestration, Kubernetes, registries, pods | | `serverless` | Functions, step functions, event-driven compute | | `database` | Relational, NoSQL, caches, search engines, data warehouses, graph databases | | `storage` | Object storage, block storage, file systems, backups, archives | | `network` | VPCs, subnets, load balancers, DNS, VPN, firewalls, CDN | | `IAM` | IAM users, roles, policies, access keys, service accounts, directories | | `messaging` | Queues, topics, event buses, streaming, email services | | `security` | WAF, secrets, KMS, certificates, security tools, defenders, DDoS protection | | `monitoring` | Logs, metrics, alerts, audit trails, observability, config tracking | | `api_gateway` | API management, REST APIs, GraphQL endpoints | | `ai_ml` | Machine learning, AI services, notebooks, training, LLM | | `governance` | Accounts, organizations, projects, policies, settings, compliance tools | | `collaboration` | Productivity SaaS apps (Exchange, Teams, SharePoint) | | `devops` | CI/CD, infrastructure as code, automation, code repositories, version control | | `analytics` | Data warehouses, query engines, ETL pipelines, BI tools, data lakes | The group is determined by the resource type being audited, not the service. For example, an EC2 security group check would use `network` (not `compute`), while an EC2 instance check would use `compute`. #### Description A concise, natural language explanation that **clearly describes what the finding means**, focusing on clarity and context rather than technical implementation details. Use simple paragraphs with line breaks if needed, but avoid sections, code blocks, or complex formatting. This field is limited to maximum 400 characters. For detailed writing guidelines and common mistakes to avoid, see [Description Guidelines](/developer-guide/check-metadata-guidelines#description-guidelines). #### Risk A clear, natural language explanation of **why this finding poses a cybersecurity risk**. Focus on how it may impact confidentiality, integrity, or availability. If those do not apply, describe any relevant operational or financial risks. Use simple paragraphs with line breaks if needed, but avoid sections, code blocks, or complex formatting. Limit your explanation to 400 characters. For detailed writing guidelines and common mistakes to avoid, see [Risk Guidelines](/developer-guide/check-metadata-guidelines#risk-guidelines). #### RelatedUrl *Deprecated*. Use `AdditionalURLs` for adding your URLs references. #### AdditionalURLs > [!WARNING] > > URLs must be valid and not repeated. A list of official documentation URLs for further reading. These should be authoritative sources that provide additional context, best practices, or detailed information about the security control being checked. Prefer official provider documentation, security standards, or well-established security resources. Avoid third-party blogs or unofficial sources unless they are highly reputable and directly relevant. #### Remediation Provides both code examples and best practice recommendations for addressing the security issue. * **Code**: Contains remediation examples in different formats: * **CLI**: Command-line interface commands to make the finding compliant in runtime. * **NativeIaC**: Native Infrastructure as Code templates with an example of a compliant configuration. For now it applies to: * **AWS**: CloudFormation YAML formatted code (do not use JSON format). * **Azure**: Bicep formatted code (do not use ARM templates). * **Terraform**: HashiCorp Configuration Language (HCL) code with an example of a compliant configuration. * **Other**: Manual steps through web interfaces or other tools to make the finding compliant. For detailed guidelines on writing remediation code, see [Remediation Code Guidelines](/developer-guide/check-metadata-guidelines#remediation-code-guidelines). * **Recommendation** * **Text**: Generic best practice guidance in natural language using Markdown format (maximum 400 characters). For writing guidelines, see [Recommendation Guidelines](/developer-guide/check-metadata-guidelines#recommendation-guidelines). * **Url**: [Prowler Hub URL](https://hub.prowler.com/) of the check. This URL is always composed by `https://hub.prowler.com/check/`. #### Categories One or more functional groupings used for execution filtering (e.g., `internet-exposed`). Categories must match the predefined values enforced by `CheckMetadata`; adding a new category requires updating the validator and the metadata documentation. For the complete list of available categories, see [Categories Guidelines](/developer-guide/check-metadata-guidelines#categories-guidelines). #### DependsOn List of check IDs of checks that if are compliant, this check will be a compliant too or it is not going to give any finding. #### RelatedTo List of check IDs of checks that are conceptually related, even if they do not share a technical dependency. #### Notes Any additional information not covered in the above fields. ### Python Model Reference The metadata structure is enforced in code using a Pydantic model. For reference, see the [`CheckMetadata`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py). ## Generic Check Patterns and Best Practices ### Common Patterns * Every check is implemented as a class inheriting from `Check` (from `prowler.lib.check.models`). * The main logic is implemented in the `execute()` method (**only method that must be implemented**), which always returns a list of provider-specific report objects (e.g., `CheckReport`)—one per finding/resource. If there are no findings/resources, return an empty list. * **Never** use the provider's client directly; instead, use the service client (e.g., `_client`) and iterate over its resources. * For each resource, create a provider-specific report object, populate it with metadata, resource details, status (`PASS`, `FAIL`, etc.), and a human-readable `status_extended` message. * Use the `metadata()` method to attach check metadata to each report. * Checks are designed to be idempotent and stateless: they do not modify resources, only report on their state. ### Best Practices * Use clear, actionable, and user-friendly language in `status_extended` to explain the result. Always provide information to identify the resource. * Use helper functions/utilities for repeated logic to avoid code duplication. Save them in the `lib` folder of the service. * Handle exceptions gracefully: catch errors per resource, log them, and continue processing other resources. * Never report `FAIL` because data could not be retrieved (missing permissions, API not enabled, feature not licensed). Emit a single `MANUAL` finding explaining what is required instead; see [Permission and Data-Availability Errors Are Not Findings](#permission-and-data-availability-errors-are-not-findings). * Document the check with a class and function level docstring explaining what it does, what it checks, and any caveats or provider-specific behaviors. * Use type hints for the `execute()` method (e.g., `-> list[CheckReport]`) for clarity and static analysis. * Ensure checks are efficient; avoid excessive nested loops. If the complexity is high, consider refactoring the check. * Keep the check logic focused: one check = one control/requirement. Avoid combining unrelated logic in a single check. ## Specific Check Patterns Details for specific providers can be found in documentation pages named using the pattern `-details`. Checks that scan resources for plaintext secrets follow a dedicated batched structure. Refer to [Secret-Scanning Checks](/developer-guide/secret-scanning-checks) before creating or updating one. # Configurable Checks in Prowler Source: https://docs.prowler.com/developer-guide/configurable-checks Prowler empowers users to extend and adapt cloud security coverage by making checks configurable through the use of the `audit_config` object. This approach enables customization of checks to meet specific requirements through a configuration file. ## Understanding the `audit_config` Object The `audit_config` object is a dictionary attached to each provider's service client (for example, `_client.audit_config`). This object loads configuration values from the main configuration file (`prowler/config/config.yaml`). Use `audit_config` to make checks flexible and user-configurable. ## Using `audit_config` to Configure Checks Retrieve configuration values in a check by using the `.get()` method on the `audit_config` object. For example, to get the minimum number of Availability Zones for Lambda from the configuration file, use the following code. If the value is not set in the configuration, the check defaults to 2: ```python theme={null} LAMBDA_MIN_AZS = awslambda_client.audit_config.get("lambda_min_azs", 2) ``` Always provide a default value in `.get()` to ensure the check works even if the configuration is missing the variable. ### Example: Security Group Rule Limit ```python title="ec2_securitygroup_with_many_ingress_egress_rules.py" theme={null} class ec2_securitygroup_with_many_ingress_egress_rules(Check): def execute(self): findings = [] max_security_group_rules = ec2_client.audit_config.get( "max_security_group_rules", 50 ) for security_group_arn, security_group in ec2_client.security_groups.items(): # ... check logic ... ``` ## Required File Updates for Configurable Variables When adding a new configurable check to Prowler, update the following files: * **Configuration File:** Add the new variable under the relevant provider or service section in `prowler/config/config.yaml`. ```yaml theme={null} # aws.awslambda_function_vpc_multi_az lambda_min_azs: 2 ``` * **Provider Schema:** Add the typed field to the provider's Pydantic schema in `prowler/config/schema/.py`. This is required: the loader validates user configs against these schemas and the shipped `config.yaml` must round-trip with zero warnings. See [Adding a Parameter to the Provider Schema](#adding-a-parameter-to-the-provider-schema) below. * **Test Fixtures:** If tests depend on this configuration, add the variable to `tests/config/fixtures/config.yaml`. * **Documentation:** Document the new variable in the list of configurable checks in [Configuration File](/user-guide/cli/tutorials/configuration_file) (`docs/user-guide/cli/tutorials/configuration_file.mdx`). For a complete list of checks that already support configuration, see the [Configuration File Tutorial](/user-guide/cli/tutorials/configuration_file). > [!NOTE] > > Because a configurable check's verdict depends on the `audit_config` value it reads, a compliance requirement can lose meaning if the scan ran with a looser threshold than the control demands. Compliance frameworks can guard against this with **configuration guardrails**: a requirement declares the strictest configuration it tolerates and is forced to FAIL when the scan's config falls short. See [Configuration Guardrails for Requirements](/developer-guide/security-compliance-framework#configuration-guardrails-for-requirements). ## Adding a Parameter to the Provider Schema Most providers have a typed Pydantic schema in `prowler/config/schema/`, registered in `prowler/config/schema/registry.py`. When a config is loaded and the provider has a registered schema, `validate_provider_config` checks each user-supplied key against it, logs a warning, and drops any field that fails validation. The consumer's `.get(key, default)` then falls back to the built-in default. Providers without a registered schema are passed through unchanged. This catches typos in a value (for example, `0.2` typed as `20`, or `"medium"` for an enum that expects `"MEDIUM"`). It does NOT catch typos in a key name: `disalowed_regions` (one `l` missing) is treated as an unknown key and passes through untouched, because third-party check plugins legitimately rely on unknown keys being preserved. Reviewers should still check that any new key the YAML adds is named exactly the same as the field on the schema. ### Where to Add the Field 1. Open `prowler/config/schema/.py` (for example, `aws.py`). 2. Add a field on the provider's schema class. Always make it `Optional[...] = None` so the absence of the key is valid. 3. Apply the tightest type the value allows. Examples below. If you are introducing an entirely new provider rather than a new parameter, also add an entry mapping the provider name to its schema class in `prowler/config/schema/registry.py`. The loader uses that registry to find the schema for the provider it is loading. ### Choosing the Right Type | Value kind | Field declaration | | - | - | | Boolean toggle | `Optional[bool] = None` | | Strictly positive integer (days, counts) | `Optional[int] = Field(default=None, gt=0)` | | Fraction in 0..1 (threshold) | `Optional[float] = Field(default=None, ge=0.0, le=1.0)` | | Closed set of strings | `Optional[Literal["A", "B", "C"]] = None` | | Free-form string | `Optional[str] = None` | | List of strings or ints | `Optional[list[str]] = None` | Prefer `Literal[...]` over `str` whenever the value is one of a known set. Prefer `Field(gt=0)` over `int` whenever zero or negative would be nonsensical. The point of the schema is to catch real-world mistakes that previously passed silently. ### Custom Validators (Only When Needed) If the value has structural rules beyond type and range, add a `field_validator`. Examples already in `aws.py`: * `_validate_port_range` rejects ports outside `0..65535`. * `_validate_account_ids` rejects anything that isn't a 12-digit AWS account ID. * `_validate_trusted_ips` rejects entries that aren't a valid IP or CIDR. Raise `ValueError` from the validator. The framework converts the error into a warning and drops the offending key. ### Example: Adding a New Parameter Say a new check needs `max_iam_role_session_hours`, a strictly positive integer that defaults to 12 in code. 1. **Schema** (`prowler/config/schema/aws.py`): ```python theme={null} # IAM max_iam_role_session_hours: Optional[int] = Field(default=None, gt=0) ``` 2. **Shipped config** (`prowler/config/config.yaml`): ```yaml theme={null} # aws.iam_role_session_duration_within_limit max_iam_role_session_hours: 12 ``` 3. **Consumer** (the check): ```python theme={null} max_hours = iam_client.audit_config.get("max_iam_role_session_hours", 12) ``` 4. **Tests** in `tests/config/schema/aws_schema_test.py`: * one test for a valid value that round-trips, * one test for an invalid value (zero, negative, wrong type) that is dropped. ### What the Loader Guarantees * **Unknown keys pass through.** Third-party check plugins can introduce arbitrary keys without schema edits; they will not be filtered. * **Invalid values never crash the run.** They produce a single warning per field and the key is dropped. * **Coerced values are normalized.** A YAML-quoted `"180"` for an `int` field arrives downstream as the integer `180`. * **The shipped `config.yaml` must round-trip cleanly.** The integration test `test_shipped_default_config_loads_without_warnings` will fail if a key is added to the YAML without a matching schema field, so the two stay in sync. ## Configuration Value Limits Configurable thresholds enforce hard limits. A value outside the documented range is **dropped with a warning** and the check falls back to its built-in default (the same as if the key were absent). These bounds are intentionally conservative: they are not the absolute service maxima but the range that still produces a meaningful security check. Use this section as the reference when upgrading an existing config: if a value you set is being rejected, it is outside the range below. Only fields with a numeric range, a fixed value set, or a length cap are listed. Fields typed as free-form strings or lists (for example `disallowed_regions`, `secrets_ignore_patterns`, `trusted_account_ids`) have no range limit — they are validated for shape only (a 12-digit account ID, a valid IP/CIDR, a dotted version string), not for magnitude. ### AWS | Key | Allowed range | Notes | | - | - | - | | `max_unused_access_keys_days` | `30..180` days | CIS AWS 1.13 recommends 45; NIST IA-5 ≤90 | | `max_console_access_days` | `30..180` days | CIS AWS 1.12 recommends 45 | | `max_unused_sagemaker_access_days` | `7..180` days | | | `max_security_group_rules` | `1..1000` | AWS hard limit is 1000 rules per security group | | `max_ec2_instance_age_in_days` | `1..1095` days | 3 years | | `max_ec2_instance_stopped_days` | `1..1095` days | 3 years | | `ec2_high_risk_ports` | each port `1..65535` | port 0 is reserved | | `max_idle_disconnect_timeout_in_seconds` | `60..1800` s | NIST AC-12: cap at 30 min | | `max_disconnect_timeout_in_seconds` | `60..3600` s | | | `max_session_duration_seconds` | `600..86400` s | 10 min .. 24 h (AppStream per-session hard limit) | | `lambda_min_azs` | `1..6` | | | `recommended_cdk_bootstrap_version` | `1..100` | | | `log_group_retention_days` | one of `1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653` | only the CloudWatch Logs API-accepted retention values | | `threat_detection_privilege_escalation_threshold` | `0.0..1.0` | fraction of suspicious actions | | `threat_detection_privilege_escalation_minutes` | `5..43200` min | under 5 min the signal is mostly false positives | | `threat_detection_enumeration_threshold` | `0.0..1.0` | | | `threat_detection_enumeration_minutes` | `5..43200` min | | | `threat_detection_llm_jacking_threshold` | `0.0..1.0` | | | `threat_detection_llm_jacking_minutes` | `5..43200` min | | | `days_to_expire_threshold` (ACM) | `7..365` days | PCI-DSS 4.2.1.1: alert ≥30 days before expiry | | `elb_min_azs` | `1..6` | | | `elbv2_min_azs` | `1..6` | | | `minimum_snapshot_retention_period` | `1..35` days | ElastiCache service hard limit | | `max_days_secret_unused` | `7..365` days | | | `max_days_secret_unrotated` | `1..180` days | NIST IA-5: rotate quarterly; CIS ≤90 | | `min_kinesis_stream_retention_hours` | `24..8760` h | 1 day .. 1 year | | `inspector2_max_days_since_last_scan` | `1..90` days | | | `inspector2_active_finding_max_age_days` | `1..365` days | Default `192` matches the FedRAMP 20x rule that marks vulnerabilities still open after 192 days as accepted | | `shodan_api_key` | ≤512 chars | | ### Azure | Key | Allowed range | Notes | | - | - | - | | `vm_backup_min_daily_retention_days` | `7..9999` days | Azure Backup hard limit; under 7 days defeats DR/ransomware recovery | | `apim_threat_detection_llm_jacking_threshold` | `0.0..1.0` | fraction of suspicious actions | | `apim_threat_detection_llm_jacking_minutes` | `5..43200` min | under 5 min the signal is mostly false positives | | `shodan_api_key` | ≤512 chars | | ### GCP | Key | Allowed range | Notes | | - | - | - | | `mig_min_zones` | `1..5` | | | `max_snapshot_age_days` | `1..1095` days | 3 years | | `max_unused_account_days` | `30..365` days | | | `storage_min_retention_days` | `1..3650` days | | | `shodan_api_key` | ≤512 chars | | ### Kubernetes | Key | Allowed range | Notes | | - | - | - | | `audit_log_maxbackup` | `2..1000` | CIS Kubernetes 1.2.18 recommends ≥10 | | `audit_log_maxsize` | `10..10000` MB | CIS Kubernetes 1.2.19 recommends ≥100 MB | | `audit_log_maxage` | `7..3650` days | CIS Kubernetes 1.2.17 recommends ≥30 days | ### M365 | Key | Allowed range | Notes | | - | - | - | | `sign_in_frequency` | `1..168` h | 1 h .. 7 days; Conditional Access baseline for admins ≤24 h | | `recommended_mailtips_large_audience_threshold` | `5..10000` | Microsoft default 25 | | `audit_log_age` | `30..3650` days | M365 E3 default 90 days; SEC/FINRA require ≥7 years | ### GitHub | Key | Allowed range | Notes | | - | - | - | | `inactive_not_archived_days_threshold` | `30..3650` days | CIS GitHub recommends 180 | ### Cloudflare | Key | Allowed range | Notes | | - | - | - | | `max_retries` | `0..10` | 0 disables retries | ### MongoDB Atlas | Key | Allowed range | Notes | | - | - | - | | `max_service_account_secret_validity_hours` | `1..720` h | 1 h .. 30 days | ### Vercel | Key | Allowed range | Notes | | - | - | - | | `days_to_expire_threshold` | `7..365` days | PCI-DSS 4.2.1.1: alert ≥30 days before expiry | | `stale_token_threshold_days` | `30..3650` days | NIST AC-2(3) typical window 30..90 days | | `stale_invitation_threshold_days` | `7..365` days | | | `max_owner_percentage` | `1..50` % | guidance recommends ≤25% | | `max_owners` | `1..1000` | absolute cap, overrides percentage for large teams | These bounds live in the provider schemas under `prowler/config/schema/`; each field's `Field(ge=..., le=...)` (or `field_validator`) is the source of truth and the descriptions there carry the full rationale. This approach ensures that checks are easily configurable, making Prowler highly adaptable to different environments and requirements. # Debugging in Prowler Source: https://docs.prowler.com/developer-guide/debugging Debugging in Prowler simplifies the development process, allowing developers to efficiently inspect and resolve unexpected issues during execution. ## Debugging with Visual Studio Code Visual Studio Code (also referred to as VSCode) provides an integrated debugger for executing and analyzing Prowler code. Refer to the official VSCode debugger [documentation](https://code.visualstudio.com/docs/editor/debugging) for detailed instructions. ### Debugging Configuration Example The following file is an example of a [debugging configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) file for [Visual Studio Code](https://code.visualstudio.com/). This file must be placed inside the *.vscode* directory and named *launch.json*: ```json theme={null} { "version": "0.2.0", "configurations": [ { "name": "Debug AWS Check", "type": "debugpy", "request": "launch", "program": "prowler-cli.py", "args": [ "aws", "--log-level", "ERROR", "-c", "" ], "console": "integratedTerminal", "justMyCode": false }, { "name": "Debug Azure Check", "type": "debugpy", "request": "launch", "program": "prowler-cli.py", "args": [ "azure", "--sp-env-auth", "--log-level", "ERROR", "-c", "" ], "console": "integratedTerminal", "justMyCode": false }, { "name": "Debug GCP Check", "type": "debugpy", "request": "launch", "program": "prowler-cli.py", "args": [ "gcp", "--log-level", "ERROR", "-c", "" ], "console": "integratedTerminal", "justMyCode": false }, { "name": "Debug K8s Check", "type": "debugpy", "request": "launch", "program": "prowler-cli.py", "args": [ "kubernetes", "--log-level", "ERROR", "-c", "" ], "console": "integratedTerminal", "justMyCode": false } ] } ``` # Contributing to Documentation Source: https://docs.prowler.com/developer-guide/documentation Prowler documentation is built using [Mintlify](https://www.mintlify.com/docs), allowing contributors to easily add or enhance documentation. ## Documentation Structure The Prowler documentation is organized into several sections. The main ones are: * **Getting Started**: Provides an overview of the Prowler platform and its two product families, Prowler Products (Prowler Cloud, Prowler Hub, Prowler MCP, Prowler Lighthouse AI) and Open Source (Prowler CLI, Prowler Local Server). This section helps new users understand which Prowler solution best fits their needs and includes product comparisons. * **Guides**: Contains practical tutorials and how-to guides organized by product (Prowler Cloud, CLI) and provider (AWS, Azure, GCP, Kubernetes, Microsoft 365, GitHub, etc.). This section covers authentication, integrations, compliance, and advanced usage scenarios. * **Developer Guide**: Documentation for contributors looking to extend Prowler functionality. This includes guides on creating providers, services, checks, output formats, integrations, and compliance frameworks. Provider-specific implementation details and testing strategies are also covered here. * **Troubleshooting**: Common issues, error messages, and their solutions. This section helps users resolve problems encountered during installation, configuration, or execution. ## AI-Driven Documentation As mentioned in the [Introduction](/developer-guide/introduction#ai-driven-contributions), we have specialized resources to enhance AI-driven development. This includes the [AGENTS.md](https://github.com/prowler-cloud/prowler/blob/master/docs/AGENTS.md) file that contains the guidelines and style guide for the AI agents in the Prowler documentation. ## Local Development **1. Install Mintlify CLI** ```bash theme={null} npm install --global mint@4.2.560 ``` For detailed instructions, check the [Mintlify documentation](https://www.mintlify.com/docs/installation). **2. Preview Documentation Locally** Start the local development server to preview changes in real-time. ```bash theme={null} mint dev ``` A local preview of your documentation will be available at [http://localhost:3000](http://localhost:3000) **3. Make Documentation Changes** Edit existing Markdown (.mdx) files inside the `docs` directory or add new documents. For reference about formatting, check the [Mintlify documentation](https://www.mintlify.com/docs/create/text). To add new sections or files, update the [`docs/docs.json`](https://github.com/prowler-cloud/prowler/blob/master/docs/docs.json) file to include them in the navigation. **4. Submit Changes** Once documentation updates are complete, [submit a pull request for review](/developer-guide/introduction#sending-the-pull-request). The Prowler team will assess and merge contributions. Your efforts help improve Prowler documentation. Thank you for contributing! 🤘 # End-2-End Tests for Prowler Local Server Source: https://docs.prowler.com/developer-guide/end2end-testing End-to-end (E2E) tests validate complete user flows in Prowler Local Server (UI + API). These tests are implemented with [Playwright](https://playwright.dev/) under the `ui/tests` folder and are designed to run against a Prowler Local Server environment. ## General Recommendations When adding or maintaining E2E tests for Prowler Local Server, follow these guidelines: 1. **Test real user journeys** Focus on full workflows (for example, sign-up → login → add provider → launch scan) instead of low-level UI details already covered by unit or integration tests. 2. **Group tests by entity or feature area** * Organize E2E tests by entity or feature area (for example, `providers.spec.ts`, `scans.spec.ts`, `invitations.spec.ts`, `sign-up.spec.ts`). * Each entity should have its own test file and corresponding page model class (for example, `ProvidersPage`, `ScansPage`, `InvitationsPage`). * Related tests for the same entity should be grouped together in the same test file to improve maintainability and make it easier to find and update tests for a specific feature. 3. **Use a Page Model (Page Object Model)** * Encapsulate selectors and common actions in page classes instead of repeating them in each test. * Leverage and extend the existing Playwright page models in `ui/tests`—such as `ProvidersPage`, `ScansPage`, and others—which are all based on the shared `BasePage`. * Page models for Prowler Local Server pages should be placed in their respective entity folders (for example, `ui/tests/providers/providers-page.ts`). * Page models for external pages (not part of Prowler Local Server) should be grouped in the `external` folder (for example, `ui/tests/external/github-page.ts`). * This approach improves readability, reduces duplication, and makes refactors safer. 4. **Reuse authentication states (StorageState)** * Multiple authentication setup projects are available that generate pre-authenticated state files stored in `playwright/.auth/`. Each project requires specific environment variables: * `admin.auth.setup` – Admin users with full system permissions (requires `E2E_ADMIN_USER` / `E2E_ADMIN_PASSWORD`) * `manage-scans.auth.setup` – Users with scan management permissions (requires `E2E_MANAGE_SCANS_USER` / `E2E_MANAGE_SCANS_PASSWORD`) * `manage-integrations.auth.setup` – Users with integration management permissions (requires `E2E_MANAGE_INTEGRATIONS_USER` / `E2E_MANAGE_INTEGRATIONS_PASSWORD`) * `manage-account.auth.setup` – Users with account management permissions (requires `E2E_MANAGE_ACCOUNT_USER` / `E2E_MANAGE_ACCOUNT_PASSWORD`) * `manage-cloud-providers.auth.setup` – Users with cloud provider management permissions (requires `E2E_MANAGE_CLOUD_PROVIDERS_USER` / `E2E_MANAGE_CLOUD_PROVIDERS_PASSWORD`) * `unlimited-visibility.auth.setup` – Users with unlimited visibility permissions (requires `E2E_UNLIMITED_VISIBILITY_USER` / `E2E_UNLIMITED_VISIBILITY_PASSWORD`) * `invite-and-manage-users.auth.setup` – Users with user invitation and management permissions (requires `E2E_INVITE_AND_MANAGE_USERS_USER` / `E2E_INVITE_AND_MANAGE_USERS_PASSWORD`) > [!NOTE] > > If fixtures have been applied (fixtures are used to populate the database with initial development data), you can use the user `e2e@prowler.com` with password `Thisisapassword123@` to configure the Admin credentials by setting `E2E_ADMIN_USER=e2e@prowler.com` and `E2E_ADMIN_PASSWORD=Thisisapassword123@`. * Within test files, use `test.use({ storageState: "playwright/.auth/admin_user.json" })` to load the pre-authenticated state, avoiding redundant authentication steps in each test. This must be placed at the test level (not inside the test function) to apply the authentication state to all tests in that scope. This approach is preferred over declaring dependencies in `playwright.config.ts` because it provides more control over which authentication states are used in specific tests. **Example:** ```typescript theme={null} // Use admin authentication state for all tests in this scope test.use({ storageState: "playwright/.auth/admin_user.json" }); test("should perform admin action", async ({ page }) => { // Test implementation }); ``` 5. **Tag and document scenarios** * Follow the existing naming convention for suites and test cases (for example, `SCANS-E2E-001`, `PROVIDER-E2E-003`) and use tags such as `@e2e`, `@serial` and feature tags (for example, `@providers`, `@scans`, `@aws`) to filter and organize tests. **Example:** ```typescript theme={null} test( "should add a new AWS provider with static credentials", { tag: [ "@critical", "@e2e", "@providers", "@aws", "@serial", "@PROVIDER-E2E-001", ], }, async ({ page }) => { // Test implementation } ); ``` * Document each one in the Markdown files under `ui/tests`, including **Priority**, **Tags**, **Description**, **Preconditions**, **Flow steps**, **Expected results**, **Key verification points** and **Notes**. **Example** ```Markdown theme={null} ## Test Case: `SCANS-E2E-001` - Execute On-Demand Scan **Priority:** `critical` **Tags:** - type → @e2e, @serial - feature → @scans **Description/Objective:** Validates the complete flow to execute an on-demand scan selecting a provider by UID and confirming success on the Scans page. **Preconditions:** - Admin user authentication required (admin.auth.setup setup) - Environment variables configured for : E2E_AWS_PROVIDER_ACCOUNT_ID,E2E_AWS_PROVIDER_ACCESS_KEY and E2E_AWS_PROVIDER_SECRET_KEY - Remove any existing AWS provider with the same Account ID before starting the test - This test must be run serially and never in parallel with other tests, as it requires the Account ID Provider to be already registered. ### Flow Steps: 1. Navigate to Scans page 2. Open provider selector and choose the entry whose text contains E2E_AWS_PROVIDER_ACCOUNT_ID 3. Optionally fill scan label (alias) 4. Click "Start now" to launch the scan 5. Verify the success toast appears 6. Verify a row in the Scans table contains the provided scan label (or shows the new scan entry) ### Expected Result: - Scan is launched successfully - Success toast is displayed to the user - Scans table displays the new scan entry (including the alias when provided) ### Key verification points: - Scans page loads correctly - Provider select is available and lists the configured provider UID - "Start now" button is rendered and enabled when form is valid - Success toast message: "The scan was launched successfully." - Table contains a row with the scan label or new scan state (queued/available/executing) ### Notes: - The table may take a short time to reflect the new scan; assertions look for a row containing the alias. - Provider cleanup performed before each test to ensure clean state - Tests should run serially to avoid state conflicts. ``` 6. **Use environment variables for secrets and dynamic data** Credentials, provider identifiers, secrets, tokens must come from environment variables (for example, `E2E_AWS_PROVIDER_ACCOUNT_ID`, `E2E_AWS_PROVIDER_ACCESS_KEY`, `E2E_AWS_PROVIDER_SECRET_KEY`, `E2E_GCP_PROJECT_ID`). > [!WARNING] > > Never commit real secrets, tokens, or account IDs to the repository. 7. **Keep tests deterministic and isolated** * Use Playwright's `test.beforeEach()` and `test.afterEach()` hooks to manage test state: * **`test.beforeEach()`**: Execute cleanup or setup logic before each test runs (for example, delete existing providers with a specific account ID to ensure a clean state). * **`test.afterEach()`**: Execute cleanup logic after each test completes (for example, remove test data created during the test execution to prevent interference with subsequent tests). * Define tests as serial using `test.describe.serial()` when they share state or resources that could interfere with parallel execution (for example, tests that use the same provider account ID or create dependent resources). This ensures tests within the serial group run sequentially, preventing race conditions and data conflicts. * Use unique identifiers (for example, random suffixes for emails or labels) to prevent data collisions. 8. **Use explicit waiting strategies** * Avoid using `waitForLoadState('networkidle')` as it is unreliable and can lead to flaky tests or unnecessary delays. * Leverage Playwright's auto-waiting capabilities by waiting for specific elements to be actionable (for example, `locator.click()`, `locator.fill()`, `locator.waitFor()`). * **Prioritize selector strategies**: Prefer `page.getByRole()` over other approaches like `page.getByText()`. `getByRole()` is more resilient to UI changes, aligns with accessibility best practices, and better reflects how users interact with the application (by role and accessible name rather than implementation details). * For dynamic content, wait for specific UI elements that indicate the page is ready (for example, button becoming enabled, a specific text appearing, etc). * This approach makes tests more reliable, faster, and aligned with how users actually interact with the application. **Common waiting patterns used in Prowler E2E tests:** * **Element visibility assertions**: Use `expect(locator).toBeVisible()` or `expect(locator).not.toBeVisible()` to wait for elements to appear or disappear (Playwright automatically waits for these conditions). * **URL changes**: Use `expect(page).toHaveURL(url)` or `page.waitForURL(url)` to wait for navigation to complete. * **Element states**: Use `locator.waitFor({ state: "visible" })` or `locator.waitFor({ state: "hidden" })` when you need explicit state control. * **Text content**: Use `expect(locator).toHaveText(text)` or `expect(locator).toContainText(text)` to wait for specific text to appear. * **Element attributes**: Use `expect(locator).toHaveAttribute(name, value)` to wait for attributes like `aria-disabled="false"` indicating a button is enabled. * **Custom conditions**: Use `page.waitForFunction(() => condition)` for complex conditions that cannot be expressed with locators (for example, checking DOM element dimensions or computed styles). * **Retryable assertions**: Use `expect(async () => { ... }).toPass({ timeout })` for conditions that may take time to stabilize (for example, waiting for table rows to filter after a server request). * **Scroll into view**: Use `locator.scrollIntoViewIfNeeded()` before interacting with elements that may be outside the viewport. **Example from Prowler tests:** ```typescript theme={null} // Wait for page to load by checking main content is visible await expect(page.locator("main")).toBeVisible(); // Wait for URL change after form submission await expect(page).toHaveURL("/providers"); // Wait for button to become enabled await expect(submitButton).toHaveAttribute("aria-disabled", "false"); // Wait for loading spinner to disappear await expect(page.getByText("Loading")).not.toBeVisible(); // Wait for custom condition await page.waitForFunction(() => { const main = document.querySelector("main"); return main && main.offsetHeight > 0; }); // Wait for retryable condition (e.g., table filtering) await expect(async () => { const rowCount = await tableRows.count(); expect(rowCount).toBeLessThanOrEqual(1); }).toPass({ timeout: 20000 }); ``` ## Running Prowler Tests E2E tests for Prowler Local Server run from the `ui` project using Playwright. The Playwright configuration lives in `ui/playwright.config.ts` and defines: * `testDir: "./tests"` – location of E2E test files (relative to the `ui` project root, so `ui/tests`). * `webServer` – how to start the Next.js development server and connect to Prowler API. * `use.baseURL` – base URL for browser interactions (defaults to `http://localhost:3000` or `AUTH_URL` if set). * `reporter: [["list"]]` – uses the list reporter to display test results in a concise format in the terminal. Other reporter options are available (for example, `html`, `json`, `junit`, `github`), and multiple reporters can be configured simultaneously. See the [Playwright reporter documentation](https://playwright.dev/docs/test-reporters) for all available options. * `expect.timeout: 20000` – timeout for assertions (20 seconds). This is the maximum time Playwright will wait for an assertion to pass before considering it failed. * **Test artifacts** (in `use` configuration): By default, `trace`, `screenshot`, and `video` are set to `"off"` to minimize resource usage. To review test failures or debug issues, these can be enabled in `playwright.config.ts` by changing them to `"on"`, `"on-first-retry"`, or `"retain-on-failure"` depending on your needs. * `outputDir: "/tmp/playwright-tests"` – directory where Playwright stores test artifacts (screenshots, videos, traces) during test execution. * **CI-specific configuration**: The configuration uses different settings when running in CI environments (detected via `process.env.CI`): * **Retries**: `2` retries in CI (to handle flaky tests), `0` retries locally (for faster feedback during development). * **Workers**: `1` worker in CI (sequential execution for stability), `undefined` locally (parallel execution by default for faster test runs). ### Prerequisites Before running E2E tests: * **Install root and UI dependencies** * Follow the [developer guide introduction](/developer-guide/introduction#getting-the-code-and-installing-all-dependencies) to clone the repository and install core dependencies. * From the `ui` directory, install frontend dependencies: ```bash theme={null} cd ui pnpm install pnpm run test:e2e:install # Install Playwright browsers ``` * **Ensure Prowler API is available** * By default, Playwright uses `UI_API_BASE_URL=http://localhost:8080/api/v1` (configured in `playwright.config.ts`). * Start Prowler API so it is reachable on that URL (for example, via `docker-compose-dev.yml` or the development orchestration used locally). * If a different API URL is required, set `UI_API_BASE_URL` accordingly before running the tests. * **Ensure Prowler Local Server UI is available** * Playwright automatically starts the Next.js server through the `webServer` block in `playwright.config.ts` (`pnpm run dev` by default). * If the UI is already running on `http://localhost:3000`, Playwright will reuse the existing server when `reuseExistingServer` is `true`. * **Configure E2E environment variables** * Suite-specific variables (for example, provider account IDs, credentials, and E2E user data) must be provided before running tests. * They can be defined either: * As exported environment variables in the shell before executing the Playwright commands, or * In a `.env.local` or `.env` file under `ui/`, and then loaded into the shell before running tests, for example: ```bash theme={null} cd ui set -a source .env.local # or .env set +a ``` * Refer to the Markdown documentation files in `ui/tests` for each E2E suite (for example, the `*.md` files that describe sign-up, providers, scans, invitations, and other flows) to see the exact list of required variables and their meaning. * Each E2E test suite explicitly checks that its required environment variables are defined at runtime and will fail with a clear error message if any mandatory variable is missing, making misconfiguration easy to detect. ### Executing Tests To execute E2E tests for Prowler Local Server: 1. **Run the full E2E suite (headless)** From the `ui` directory: ```bash theme={null} pnpm run test:e2e ``` This command runs Playwright with the configured projects. 2. **Run E2E tests with the Playwright UI runner** ```bash theme={null} pnpm run test:e2e:ui ``` This opens the Playwright test runner UI to inspect, debug, and rerun specific tests or projects. 3. **Debug E2E tests interactively** ```bash theme={null} pnpm run test:e2e:debug ``` Use this mode to step through flows, inspect selectors, and adjust timings. It runs tests in headed mode with debugging tools enabled. 4. **Run tests in headed mode without debugger** ```bash theme={null} pnpm run test:e2e:headed ``` This is useful to visually confirm flows while still running the full suite. 5. **View previous test reports** ```bash theme={null} pnpm run test:e2e:report ``` This opens the latest Playwright HTML report, including traces and screenshots when enabled. 6. **Run specific tests or subsets** In addition to the predefined scripts, Playwright allows filtering which tests run. These examples use the Playwright CLI directly through `pnpm`: * **By test ID (`@ID` in the test metadata or description)** To run a single test case identified by its ID (for example, `@PROVIDER-E2E-001` or `@SCANS-E2E-001`): ```bash theme={null} pnpm playwright test --grep @PROVIDER-E2E-001 ``` * **By tags** To run all tests that share a common tag (for example, all provider E2E tests tagged with `@providers`): ```bash theme={null} pnpm playwright test --grep @providers ``` This is useful to focus on a specific feature area such as providers, scans, invitations, or sign-up. * **By Playwright project** To run only the tests associated with a given project defined in `playwright.config.ts` (for example, `providers` or `scans`): ```bash theme={null} pnpm playwright test --project=providers ``` Combining project and grep filters is also supported, enabling very narrow runs (for example, a single test ID within the `providers` project). For additional CLI options and combinations, see the [Playwright command line documentation](https://playwright.dev/docs/test-cli). > [!NOTE] > > For detailed flows, preconditions, and environment variable requirements per feature, always refer to the Markdown files in `ui/tests`. Those documents are the single source of truth for business expectations and validation points in each E2E suite. # Environment Variable Naming Convention Source: https://docs.prowler.com/developer-guide/environment-variables Prowler is a monorepo composed of several runtime components — Prowler Local Server (the web user interface), Prowler API (the backend), Prowler SDK, and Prowler MCP Server (Model Context Protocol) — that frequently share a single `.env` file. To keep that shared configuration unambiguous, each component namespaces its environment variables with a component-specific prefix. ## Component Prefixes Each component owns a dedicated prefix for the environment variables it reads: | Component | Prefix | Status | | - | - | - | | Prowler Local Server (web UI) | `UI_` | Adopted | | Prowler API (backend) | `API_` | Planned | | Prowler SDK | `SDK_` | Planned | | Prowler MCP Server | `MCP_` | Planned | ## Why Component Prefixes Matter Component prefixes solve three concrete problems in a shared configuration file: * **Collisions in a shared `.env`:** Several components historically read identically named variables. The API base URL, for example, is consumed by more than one component, so a single unprefixed name is ambiguous. A component prefix removes that ambiguity. * **Explicit ownership:** A prefix states, at a glance, which component consumes a variable. * **Reduced accidental exposure:** For Prowler Local Server, scoping browser-facing configuration under one intentional prefix prevents server-only values from leaking into the client bundle. ## Prowler Local Server Prowler Local Server has adopted the `UI_` prefix. Its public configuration is resolved from the container environment at runtime rather than inlined at build time, so a single pre-built image serves any deployment. For the operational details on changing these values without rebuilding the image, see [Troubleshooting](/troubleshooting). The former build-time variables map to the new runtime variables as follows: | Former variable | New variable | | - | - | | `NEXT_PUBLIC_API_BASE_URL` | `UI_API_BASE_URL` | | `NEXT_PUBLIC_API_DOCS_URL` | `UI_API_DOCS_URL` | | `NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID` | `UI_GOOGLE_TAG_MANAGER_ID` | | `NEXT_PUBLIC_SENTRY_DSN`, `SENTRY_DSN` | `UI_SENTRY_DSN` | | `NEXT_PUBLIC_SENTRY_ENVIRONMENT`, `SENTRY_ENVIRONMENT` | `UI_SENTRY_ENVIRONMENT` | | `NEXT_PUBLIC_IS_CLOUD_ENV` | `UI_CLOUD_ENABLED` | `UI_CLOUD_ENABLED` is a plain runtime boolean flag that enables Prowler Cloud behavior when set to the exact string `"true"` and defaults to off; unlike the other renamed variables it has no legacy fallback, so `NEXT_PUBLIC_IS_CLOUD_ENV` is no longer read. `UI_SELF_REGISTRATION_ENABLED` is a runtime opt-out flag that Prowler Local Server reads only when `UI_CLOUD_ENABLED` is `"true"`. It defaults to on and turns off when set to `"false"`, matched case-insensitively so the same value can be shared with a backend setting written `False`. When it is off, the sign-up page only opens with an invitation token, the sign-in page drops its "Sign up" link, and the profile hides "Create organization"; invited users can still complete their registration. Outside a Prowler Cloud deployment the flag is ignored and account creation stays open. ## Registry UI Rollout and Rollback `UI_REGISTRY_ENABLED` is an optional runtime flag for Prowler Cloud and Private Cloud. Registry is eligible only when both `UI_CLOUD_ENABLED` and `UI_REGISTRY_ENABLED` are the exact string `"true"` and the current user has the backend-authorized `manage_registry` permission. Unset, `"false"`, or malformed values fail closed. The flag defaults to off and is not a replacement for backend authorization. Registry access is independent of billing; Private Cloud can use it with `CLOUD_BILLING_ENABLED=false`. Roll out Registry only after the Registry backend dependency is deployed, intended roles have `manage_registry`, and acceptance with real credentials has exercised installation, provider account creation, credentials, connection, and scan launch. Deploy the UI with `UI_REGISTRY_ENABLED` unset or `"false"`; set it to `"true"` only in the prepared process environment, then restart or otherwise apply the environment update required by the platform. A Registry key must belong to the configured Registry environment; a production key does not authenticate against a development Registry. The Registry links read `PROWLER_REGISTRY_INDEX_URL`, the same base URL the backend installs artifacts from. The Registry page and the credential banner link to it, and its origin is allowed for images. `UI_REGISTRY_MEDIA_URL` adds the Registry media service origin so artifact logos load. When `PROWLER_REGISTRY_INDEX_URL` is unset or invalid, the links are hidden instead of pointing to the public Prowler Registry, which keeps private and air-gapped deployments from sending users to an unreachable host. `UI_REGISTRY_URL` is no longer read. The catalog displays all artifacts, including built-ins and packages containing only checks or compliance frameworks. Only external provider artifacts support Add. After confirmed installation, open Providers and select the option labeled Registry to configure an account. Creating accounts and running scans also require the corresponding provider and scan permissions. Removing an artifact keeps existing provider accounts, but future connections or scans can fail until the artifact is installed again. To roll back, set `UI_REGISTRY_ENABLED=false` or remove it and apply the environment update. Proxy, page, and action checks deny on their next request. Navigation refreshes from server-authorized access when the page is requested again. Rollback does not delete Registry credentials, tenant artifact records, or provider accounts. The build-time-only Sentry variables used for source-map upload — `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_AUTH_TOKEN`, and `SENTRY_RELEASE` — keep their names, as they are not part of Prowler Local Server's runtime configuration. ## Enabling Third-Party Integrations Prowler Local Server gates each optional third-party integration behind an explicit enable flag. When an integration is configured through its new `UI_*` variables, it loads only when its flag is set to the exact string `"true"`; any other value, including unset, leaves it off. This default-off behavior keeps a deployment free of third-party egress unless it opts in. Deployments still using the deprecated legacy variable names keep loading without the flag, for backward compatibility (see [Deprecated Names](#deprecated-names)). | Integration | Enable flag | Required configuration when enabled | | - | - | - | | Sentry (error monitoring) | `UI_SENTRY_ENABLED` | `UI_SENTRY_DSN` | | Google Tag Manager | `UI_GOOGLE_TAG_MANAGER_ENABLED` | `UI_GOOGLE_TAG_MANAGER_ID` | | PostHog (product analytics) | `UI_POSTHOG_ENABLED` | `UI_POSTHOG_KEY` and `UI_POSTHOG_HOST` | When an integration is enabled but its required configuration is missing, Prowler Local Server fails fast at server startup with a clear error, so a misconfigured container never starts silently. A new `UI_*` value set while its enable flag is not `"true"` is ignored, and the server logs a one-time startup warning noting that the integration will not load. Legacy names follow the backward-compatible rule described in [Deprecated Names](#deprecated-names). PostHog support is currently limited to configuration validation: Prowler Local Server reads and validates the PostHog variables but does not yet load a PostHog client. > [!WARNING] > > Configuring an integration through the new `UI_*` variables now requires its enable flag. A deployment that adopted `UI_SENTRY_DSN` or `UI_GOOGLE_TAG_MANAGER_ID` must also set `UI_SENTRY_ENABLED=true` or `UI_GOOGLE_TAG_MANAGER_ENABLED=true` to keep the integration active. Deployments still using the legacy names (`NEXT_PUBLIC_*`, or `POSTHOG_KEY` and `POSTHOG_HOST`) keep working without the flag. ## Upcoming Breaking Change > [!WARNING] > > Adopting the `API_`, `SDK_`, and `MCP_` prefixes for Prowler API, Prowler SDK, and Prowler MCP Server is a planned breaking change in a future release. Migrate environment configuration to the new names when upgrading. Prowler API, Prowler SDK, and Prowler MCP Server have not yet adopted the convention. In a future release, the variables each of these components reads will be namespaced under `API_`, `SDK_`, and `MCP_` respectively. The per-component mapping from current to prefixed names will be documented when each change is released. ## Deprecated Names * **Prowler Local Server:** The bare server-side `SENTRY_DSN` and `SENTRY_ENVIRONMENT` are no longer read; the server and edge runtimes now read `UI_SENTRY_DSN` and `UI_SENTRY_ENVIRONMENT`. The former `NEXT_PUBLIC_*` names — and, for PostHog, the unprefixed `POSTHOG_KEY` and `POSTHOG_HOST` — are deprecated but stay backward compatible: they are read at runtime regardless of the enable flag, so an existing deployment keeps its integration active without opting in. The new `UI_*` names, by contrast, load only when the matching enable flag is set to `"true"`. These legacy names will be removed in a future release, so migrate to the `UI_*` runtime variables — and set the enable flag — on the running container. * **Prowler API, Prowler SDK, and Prowler MCP Server:** The current, unprefixed variable names are deprecated. They continue to work today and will be removed once the prefixed convention is adopted for each component, as described in [Upcoming Breaking Change](#upcoming-breaking-change). # Google Cloud Provider Source: https://docs.prowler.com/developer-guide/gcp-details This page details the [Google Cloud Platform (GCP)](https://cloud.google.com/) provider implementation in Prowler. By default, Prowler will audit all the GCP projects that the authenticated identity can access. To configure it, follow the [GCP getting started guide](/user-guide/providers/gcp/getting-started-gcp). ## GCP Provider Classes Architecture The GCP provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the GCP-specific implementation, highlighting how the generic provider concepts are realized for GCP in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### Main Class * **Location:** [`prowler/providers/gcp/gcp_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/gcp_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for GCP-specific logic, session management, credential validation, project and organization discovery, and configuration. * **Key GCP Responsibilities:** * Initializes and manages GCP sessions (supports Application Default Credentials, Service Account, OAuth, and impersonation). * Validates credentials and sets up the GCP identity context. * Loads and manages configuration, mutelist, and fixer settings. * Discovers accessible GCP projects and organization metadata. * Provides properties and methods for downstream GCP service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/gcp/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/models.py) * **Purpose:** Define structured data for GCP identity, project, and organization info. * **Key GCP Models:** * `GCPIdentityInfo`: Holds GCP identity metadata, such as the profile name. * `GCPOrganization`: Represents a GCP organization with ID, name, and display name. * `GCPProject`: Represents a GCP project with number, ID, name, organization, labels, and lifecycle state. ### `GCPService` (Service Base Class) * **Location:** [`prowler/providers/gcp/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/lib/service/service.py) * **Purpose:** Abstract base class that all GCP service-specific classes inherit from. This implements the generic service pattern (described in [service page](/developer-guide/services#service-base-class)) specifically for GCP. * **Key GCP Responsibilities:** * Receives a `GcpProvider` instance to access session, identity, and configuration. * Manages clients for all services by project. * Filters projects to only those with the relevant API enabled. * Provides `__threading_call__` method to make API calls in parallel by project or resource. * Exposes common audit context (`project_ids`, `projects`, `default_project_id`, `audit_config`, `fixer_config`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/gcp/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/exceptions/exceptions.py) * **Purpose:** Custom exception classes for GCP-specific error handling, such as credential, session, and project access errors. ### Session and Utility Helpers * **Location:** [`prowler/providers/gcp/lib/`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/lib/) * **Purpose:** Helpers for argument parsing, mutelist management, and other cross-cutting concerns. ## Retry Configuration GCP services implement automatic retry functionality for rate limiting errors (HTTP 429). This is configured centrally and must be included in all API calls: ### Required Implementation ```python theme={null} from prowler.providers.gcp.config import DEFAULT_RETRY_ATTEMPTS # In discovery.build() client = discovery.build( service, version, credentials=credentials, num_retries=DEFAULT_RETRY_ATTEMPTS ) # In request.execute() response = request.execute(num_retries=DEFAULT_RETRY_ATTEMPTS) ``` ### Configuration * **Default Value**: 3 attempts (configurable in `prowler/providers/gcp/config.py`) * **Command Line Flag**: `--gcp-retries-max-attempts` for runtime configuration * **Error Types**: HTTP 429 and quota exceeded errors * **Backoff Strategy**: Exponential backoff with randomization ### Example Service Implementation ```python theme={null} def _get_instances(self): for project_id in self.project_ids: try: client = discovery.build( "compute", "v1", credentials=self.credentials, num_retries=DEFAULT_RETRY_ATTEMPTS ) request = client.instances().list(project=project_id) response = request.execute(num_retries=DEFAULT_RETRY_ATTEMPTS) # Process response... except Exception as error: logger.error(f"{error.__class__.__name__}: {error}") ``` ## Specific Patterns in GCP Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/gcp/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/gcp/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and taking other services already implemented as reference. In next subsection you can find a list of common patterns that are used across all GCP services. ### GCP Service Common Patterns * Services communicate with GCP using the Google Cloud Python SDK, you can find the documentation with all the services [here](https://cloud.google.com/python/docs/reference). * Every GCP service class inherits from `GCPService`, ensuring access to session, identity, configuration, and client utilities. * The constructor (`__init__`) always calls `super().__init__` with the service name, provider, region (default "global"), and API version (default "v1"). Usually, the service name is the class name in lowercase, so it is called like `super().__init__(__class__.__name__, provider)`. * Resource containers **must** be initialized in the constructor, typically as dictionaries keyed by resource ID and the value is the resource object. * Only projects with the API enabled are included in the audit scope. * Resource discovery and attribute collection can be parallelized using `self.__threading_call__`, typically by region/zone or resource. * All GCP resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * Each GCP API call is wrapped in try/except blocks, always logging errors. * **Retry Configuration**: All `request.execute()` calls must include `num_retries=DEFAULT_RETRY_ATTEMPTS` for automatic retry on rate limiting errors (HTTP 429). * Tags and additional attributes that cannot be retrieved from the default call should be collected and stored for each resource using dedicated methods and threading. ## Specific Patterns in GCP Checks The GCP checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/gcp/services/iam/iam_sa_user_managed_key_unused/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/gcp/services/iam/iam_sa_user_managed_key_unused)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is following the [GCP check implementation documentation](/developer-guide/checks#creating-a-check) and taking other similar checks as reference. ### Check Report Class The `Check_Report_GCP` class models a single finding for a GCP resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `Check_Report_GCP` extends the base report structure with GCP-specific fields, enabling detailed tracking of the resource, project, and location associated with each finding. #### Constructor and Attribute Population When you instantiate `Check_Report_GCP`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its GCP-specific attributes from the resource, using the following logic (in order of precedence): * **`resource_id`**: * Uses the explicit `resource_id` argument if provided. * Otherwise, uses `resource.id` if present. * Otherwise, uses `resource.name` if present. * Defaults to an empty string if none are available. * **`resource_name`**: * Uses the explicit `resource_name` argument if provided. * Otherwise, uses `resource.name` if present. * Defaults to an empty string. * **`project_id`**: * Uses the explicit `project_id` argument if provided. * Otherwise, uses `resource.project_id` if present. * Defaults to an empty string. * **`location`**: * Uses the explicit `location` argument if provided. * Otherwise, uses `resource.location` if present. * Otherwise, uses `resource.region` if present. * Defaults to "global" if none are available. All these attributes can be overridden by passing the corresponding argument to the constructor. If the resource object does not contain the required attributes, you must set them manually. Other attributes are inherited from the `Check_Report` class, from those you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} report = Check_Report_GCP( metadata=check_metadata, resource=resource_object, resource_id="custom-id", # Optional override resource_name="custom-name", # Optional override project_id="my-gcp-project", # Optional override location="us-central1" # Optional override ) report.status = "PASS" report.status_extended = "Resource is compliant." ``` # GitHub Provider Source: https://docs.prowler.com/developer-guide/github-details This page details the [GitHub](https://github.com/) provider implementation in Prowler. By default, Prowler will audit the GitHub account - scanning all repositories, organizations, and applications that your configured credentials can access. To configure it, follow the [GitHub getting started guide](/user-guide/providers/github/getting-started-github). ## GitHub Provider Classes Architecture The GitHub provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the GitHub-specific implementation, highlighting how the generic provider concepts are realized for GitHub in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### `GithubProvider` (Main Class) * **Location:** [`prowler/providers/github/github_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/github_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for GitHub-specific logic, session management, credential validation, and configuration. * **Key GitHub Responsibilities:** * Initializes and manages GitHub sessions (supports Personal Access Token, OAuth App, and GitHub App authentication). * Validates credentials and sets up the GitHub identity context. * Loads and manages configuration, mutelist, and fixer settings. * Provides properties and methods for downstream GitHub service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/github/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/models.py) * **Purpose:** Define structured data for GitHub identity, session, and output options. * **Key GitHub Models:** * `GithubSession`: Holds authentication tokens and keys for the session. * `GithubIdentityInfo`, `GithubAppIdentityInfo`: Store account or app identity metadata. ### `GithubService` (Service Base Class) * **Location:** [`prowler/providers/github/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/lib/service/service.py) * **Purpose:** Abstract base class for all GitHub service-specific classes. * **Key GitHub Responsibilities:** * Receives a `GithubProvider` instance to access session, identity, and configuration. * Manages GitHub API clients for the authenticated user or app. * Exposes common audit context (`audit_config`, `fixer_config`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/github/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/exceptions/exceptions.py) * **Purpose:** Custom exception classes for GitHub-specific error handling, such as credential and session errors. ### Session and Utility Helpers * **Location:** [`prowler/providers/github/lib/`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/lib/) * **Purpose:** Helpers for argument parsing, mutelist management, and other cross-cutting concerns. ## Specific Patterns in GitHub Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/github/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/github/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and by taking other already implemented services as reference. ### GitHub Service Common Patterns * Services communicate with GitHub using the PyGithub Python SDK. See the [official documentation](https://pygithub.readthedocs.io/). * Every GitHub service class inherits from `GithubService`, ensuring access to session, identity, configuration, and client utilities. * The constructor (`__init__`) always calls `super().__init__` with the service name and provider (e.g. `super().__init__(__class__.__name__, provider))`). Ensure that the service name in PyGithub is the same that you use in the constructor. Usually is used the `__class__.__name__` to get the service name because it is the same as the class name. * Resource containers **must** be initialized in the constructor, typically as dictionaries keyed by resource ID or name. * All GitHub resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * GitHub API calls are wrapped in try/except blocks, always logging errors. ## Specific Patterns in GitHub Checks The GitHub checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks in: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/github/services/repository/repository_secret_scanning_enabled/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/github/services/repository/repository_secret_scanning_enabled)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is the [GitHub check implementation documentation](/developer-guide/checks#creating-a-check) and by taking other checks as reference. ### Check Report Class The `CheckReportGithub` class models a single finding for a GitHub resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `CheckReportGithub` extends the base report structure with GitHub-specific fields, enabling detailed tracking of the resource, name, and owner associated with each finding. #### Constructor and Attribute Population When you instantiate `CheckReportGithub`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its GitHub-specific attributes from the resource, using the following logic (in order of precedence): * **`resource_id`**: * Uses the explicit `resource_id` argument if provided. * Otherwise, uses `resource.id` if present. * Defaults to an empty string if not available. * **`resource_name`**: * Uses the explicit `resource_name` argument if provided. * Otherwise, uses `resource.name` if present. * Defaults to an empty string if not available. * **`owner`**: * Uses the explicit `owner` argument if provided. * Otherwise, uses `resource.owner` for repositories and `resource.name` for organizations. * Defaults to an empty string if not available. If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from which you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} report = CheckReportGithub( metadata=check_metadata, resource=resource_object ) report.status = "PASS" report.status_extended = "Resource is compliant." ``` # Integration Tests Source: https://docs.prowler.com/developer-guide/integration-testing Coming soon ... # Creating a New Integration Source: https://docs.prowler.com/developer-guide/integrations ## Introduction Integrating Prowler with external tools enhances its functionality and enables seamless workflow automation. Prowler supports a variety of integrations to optimize security assessments and reporting. ### Supported Integration Targets * Messaging Platforms – Example: Slack * Project Management Tools – Example: Jira * Cloud Services – Example: AWS Security Hub ### Integration Guidelines To integrate Prowler with a specific product: Refer to the [Prowler Developer Guide](https://docs.prowler.com/projects/prowler-open-source/en/latest/) to understand its architecture and integration mechanisms. * Identify the most suitable integration method for the intended platform. ## Steps to Create an Integration ### Defining the Integration Purpose * Before implementing an integration, clearly define its objective. Common purposes include: * Sending Prowler findings to a platform for alerting, tracking, or further analysis. * For inspiration and implementation examples, please review the existing integrations in the [`prowler/lib/outputs`](https://github.com/prowler-cloud/prowler/tree/master/prowler/lib/outputs) folder. ### Developing the Integration * Script Development: * Write a script to process Prowler’s output and interact with the target platform’s API. * If the goal is to send findings, parse Prowler’s results and use the platform’s API to create entries or notifications. * Configuration: * Ensure the script supports environment-specific settings, such as: * API endpoints * Authentication tokens * Any necessary configurable parameters. ### Fundamental Structure * Integration Class: * To implement an integration, create a class that encapsulates the required attributes and methods for interacting with the target platform. Example: Jira Integration ```python title="Jira Class" theme={null} class Jira: """ Jira class to interact with the Jira API [Note] This integration is limited to a single Jira Cloud instance, meaning all issues will be created under the same Jira Cloud ID. Future improvements will include the ability to specify a Jira Cloud ID for users associated with multiple accounts. Attributes - _redirect_uri: The redirect URI used - _client_id: The client identifier - _client_secret: The client secret - _access_token: The access token - _refresh_token: The refresh token - _expiration_date: The authentication expiration - _cloud_id: The cloud identifier - _scopes: The scopes needed to authenticate, read:jira-user read:jira-work write:jira-work - AUTH_URL: The URL to authenticate with Jira - PARAMS_TEMPLATE: The template for the parameters to authenticate with Jira - TOKEN_URL: The URL to get the access token from Jira - API_TOKEN_URL: The URL to get the accessible resources from Jira Methods __init__: Initializes the Jira object - input_authorization_code: Inputs the authorization code - auth_code_url: Generates the URL to authorize the application - get_auth: Gets the access token and refreshes it - get_cloud_id: Gets the cloud identifier from Jira - get_access_token: Gets the access token - refresh_access_token: Refreshes the access token from Jira - test_connection: Tests the connection to Jira and returns a Connection object - get_projects: Gets the projects from Jira - get_available_issue_types: Gets the available issue types for a project - send_findings: Sends the findings to Jira and creates an issue Raises: - JiraGetAuthResponseError: Failed to get the access token and refresh token - JiraGetCloudIDNoResourcesError: No resources were found in Jira when getting the cloud id - JiraGetCloudIDResponseError: Failed to get the cloud ID, response code did not match 200 - JiraGetCloudIDError: Failed to get the cloud ID from Jira - JiraAuthenticationError: Failed to authenticate - JiraRefreshTokenError: Failed to refresh the access token - JiraRefreshTokenResponseError: Failed to refresh the access token, response code did not match 200 - JiraGetAccessTokenError: Failed to get the access token - JiraNoProjectsError: No projects found in Jira - JiraGetProjectsError: Failed to get projects from Jira - JiraGetProjectsResponseError: Failed to get projects from Jira, response code did not match 200 - JiraInvalidIssueTypeError: The issue type is invalid - JiraGetAvailableIssueTypesError: Failed to get available issue types from Jira - JiraGetAvailableIssueTypesResponseError: Failed to get available issue types from Jira, response code did not match 200 - JiraCreateIssueError: Failed to create an issue in Jira - JiraSendFindingsResponseError: Failed to send the findings to Jira - JiraTestConnectionError: Failed to test the connection Usage: jira = Jira( redirect_uri="http://localhost:8080", client_id="client_id", client_secret="client_secret ) jira.send_findings(findings=findings, project_key="KEY") """ _redirect_uri: str = None _client_id: str = None _client_secret: str = None _access_token: str = None _refresh_token: str = None _expiration_date: int = None _cloud_id: str = None _scopes: list[str] = None AUTH_URL = "https://auth.atlassian.com/authorize" PARAMS_TEMPLATE = { "audience": "api.atlassian.com", "client_id": None, "scope": None, "redirect_uri": None, "state": None, "response_type": "code", "prompt": "consent", } TOKEN_URL = "https://auth.atlassian.com/oauth/token" API_TOKEN_URL = "https://api.atlassian.com/oauth/token/accessible-resources" def __init__( self, redirect_uri: str = None, client_id: str = None, client_secret: str = None, ): self._redirect_uri = redirect_uri self._client_id = client_id self._client_secret = client_secret self._scopes = ["read:jira-user", "read:jira-work", "write:jira-work"] auth_url = self.auth_code_url() authorization_code = self.input_authorization_code(auth_url) self.get_auth(authorization_code) # More properties and methods ``` * Test Connection Method: * Validating Credentials or Tokens To ensure a successful connection to the target platform, implement a method that validates authentication credentials or tokens. #### Method Implementation The following example demonstrates the `test_connection` method for the `Jira` class: ```python title="Test connection" theme={null} @staticmethod def test_connection( redirect_uri: str = None, client_id: str = None, client_secret: str = None, raise_on_exception: bool = True, ) -> Connection: """Test the connection to Jira Args: - redirect_uri: The redirect URI used - client_id: The client identifier - client_secret: The client secret - raise_on_exception: Whether to raise an exception or not Returns: - Connection: The connection object Raises: - JiraGetCloudIDNoResourcesError: No resources were found in Jira when getting the cloud id - JiraGetCloudIDResponseError: Failed to get the cloud ID, response code did not match 200 - JiraGetCloudIDError: Failed to get the cloud ID from Jira - JiraAuthenticationError: Failed to authenticate - JiraTestConnectionError: Failed to test the connection """ try: jira = Jira( redirect_uri=redirect_uri, client_id=client_id, client_secret=client_secret, ) access_token = jira.get_access_token() if not access_token: return ValueError("Failed to get access token") headers = {"Authorization": f"Bearer {access_token}"} response = requests.get( f"https://api.atlassian.com/ex/jira/{jira.cloud_id}/rest/api/3/myself", headers=headers, ) if response.status_code == 200: return Connection(is_connected=True) else: return Connection(is_connected=False, error=response.json()) except JiraGetCloudIDNoResourcesError as no_resources_error: logger.error( f"{no_resources_error.__class__.__name__}[{no_resources_error.__traceback__.tb_lineno}]: {no_resources_error}" ) if raise_on_exception: raise no_resources_error return Connection(error=no_resources_error) except JiraGetCloudIDResponseError as response_error: logger.error( f"{response_error.__class__.__name__}[{response_error.__traceback__.tb_lineno}]: {response_error}" ) if raise_on_exception: raise response_error return Connection(error=response_error) except JiraGetCloudIDError as cloud_id_error: logger.error( f"{cloud_id_error.__class__.__name__}[{cloud_id_error.__traceback__.tb_lineno}]: {cloud_id_error}" ) if raise_on_exception: raise cloud_id_error return Connection(error=cloud_id_error) except JiraAuthenticationError as auth_error: logger.error( f"{auth_error.__class__.__name__}[{auth_error.__traceback__.tb_lineno}]: {auth_error}" ) if raise_on_exception: raise auth_error return Connection(error=auth_error) except Exception as error: logger.error(f"Failed to test connection: {error}") if raise_on_exception: raise JiraTestConnectionError( message="Failed to test connection on the Jira integration", file=os.path.basename(__file__), ) return Connection(is_connected=False, error=error) ``` * Send Findings Method: * Add a method to send Prowler findings to the target platform, adhering to its API specifications. #### Method Implementation The following example demonstrates the `send_findings` method for the `Jira` class: ```python title="Send findings method" theme={null} def send_findings( self, findings: list[Finding] = None, project_key: str = None, issue_type: str = None, ): """ Send the findings to Jira Args: - findings: The findings to send - project_key: The project key - issue_type: The issue type Raises: - JiraRefreshTokenError: Failed to refresh the access token - JiraRefreshTokenResponseError: Failed to refresh the access token, response code did not match 200 - JiraCreateIssueError: Failed to create an issue in Jira - JiraSendFindingsResponseError: Failed to send the findings to Jira """ try: access_token = self.get_access_token() if not access_token: raise JiraNoTokenError( message="No token was found", file=os.path.basename(__file__), ) projects = self.get_projects() if project_key not in projects: logger.error("The project key is invalid") raise JiraInvalidProjectKeyError( message="The project key is invalid", file=os.path.basename(__file__), ) available_issue_types = self.get_available_issue_types(project_key) if issue_type not in available_issue_types: logger.error("The issue type is invalid") raise JiraInvalidIssueTypeError( message="The issue type is invalid", file=os.path.basename(__file__) ) headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json", } for finding in findings: status_color = self.get_color_from_status(finding.status.value) adf_description = self.get_adf_description( check_id=finding.metadata.CheckID, check_title=finding.metadata.CheckTitle, severity=finding.metadata.Severity.value.upper(), status=finding.status.value, status_color=status_color, status_extended=finding.status_extended, provider=finding.metadata.Provider, region=finding.region, resource_uid=finding.resource_uid, resource_name=finding.resource_name, risk=finding.metadata.Risk, recommendation_text=finding.metadata.Remediation.Recommendation.Text, recommendation_url=finding.metadata.Remediation.Recommendation.Url, ) payload = { "fields": { "project": {"key": project_key}, "summary": f"[Prowler] {finding.metadata.Severity.value.upper()} - {finding.metadata.CheckID} - {finding.resource_uid}", "description": adf_description, "issuetype": {"name": issue_type}, } } response = requests.post( f"https://api.atlassian.com/ex/jira/{self.cloud_id}/rest/api/3/issue", json=payload, headers=headers, ) if response.status_code != 201: response_error = f"Failed to send finding: {response.status_code} - {response.json()}" logger.warning(response_error) raise JiraSendFindingsResponseError( message=response_error, file=os.path.basename(__file__) ) else: logger.info(f"Finding sent successfully: {response.json()}") except JiraRefreshTokenError as refresh_error: raise refresh_error except JiraRefreshTokenResponseError as response_error: raise response_error except Exception as e: logger.error(f"Failed to send findings: {e}") raise JiraCreateIssueError( message="Failed to create an issue in Jira", file=os.path.basename(__file__), ) ``` ### Testing the Integration * Conduct integration testing in a controlled environment to validate expected behavior. Ensure the following: * Transmission Accuracy – Verify that Prowler findings are correctly sent and processed by the target platform. * Error Handling – Simulate edge cases to assess robustness and failure recovery mechanisms. ### Documentation * Ensure the following elements are included: * Setup Instructions – List all necessary dependencies and installation steps. * Configuration Details – Specify required environment variables, authentication steps, etc. * Example Use Cases – Provide practical scenarios demonstrating functionality. * Troubleshooting Guide – Document common issues and resolution steps. * Comprehensive and clear documentation improves maintainability and simplifies onboarding. # Introduction to developing in Prowler Source: https://docs.prowler.com/developer-guide/introduction Thanks for your interest in contributing to Prowler! Prowler can be extended in various ways. This guide provides the different ways to contribute and how to get started. > [!WARNING] > > Maintainers will assess whether a change fits the project roadmap and scope before merging. ## Contributing to Prowler ### Review Current Issues Check out our [GitHub Issues](https://github.com/prowler-cloud/prowler/issues) page for ideas to contribute. > [card] [Good First Issue](https://github.com/prowler-cloud/prowler/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) > > We tag issues as `good first issue` for new contributors. These are typically well-defined and manageable in scope. > [card] [Help Wanted](https://github.com/prowler-cloud/prowler/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22) > > We tag issues as `help wanted` for other issues that require more time to complete. ### Expand Prowler's Capabilities Prowler is constantly evolving. Contributions to checks, services, or integrations help improve the tool for everyone. Here is how to get involved: > [card] [Adding New Checks](/developer-guide/checks) > > Want to improve Prowler's detection capabilities for your favorite cloud provider? You can contribute by writing new checks. > [card] [Adding New Services](/developer-guide/services) > > One key service for your favorite cloud provider is missing? Add it to Prowler! Do not forget to include relevant checks to validate functionality. > [card] [Adding New Providers](/developer-guide/provider) > > If you would like to extend Prowler to work with a new cloud provider, this typically involves setting up new services and checks to ensure compatibility. > [card] [Adding New Compliance Frameworks](/developer-guide/security-compliance-framework) > > Need to ensure Prowler supports a specific compliance framework? Add new security compliance frameworks to map checks against regulatory or industry standards. > [card] [Adding New Output Formats](/developer-guide/outputs) > > Want to tailor how results are displayed or exported? You can add custom output formats. > [card] [Adding New Integrations](/developer-guide/integrations) > > Prowler can work with other tools and platforms through integrations. > [card] [Adding New Attack Paths Queries](/developer-guide/attack-paths-queries) > > Want to detect new privilege escalation or exposure patterns? Contribute read-only openCypher queries that traverse the cloud graph. > [card] [Proposing or Implementing Features](https://github.com/prowler-cloud/prowler/issues/new?template=feature-request.yml) > > Propose brand-new features or enhancements to existing ones, or help implement community-requested improvements. ### Improve Documentation Help make Prowler more accessible by enhancing our documentation, fixing typos, or adding examples/tutorials. > [card] [Documentation Guide](/developer-guide/documentation) > > Enhance our documentation, fix typos, or add examples/tutorials. ### Bug Fixes If you find any issues or bugs, you can report them in the [GitHub Issues](https://github.com/prowler-cloud/prowler/issues) page and if you want you can also fix them. > [card] [Report a Bug](https://github.com/prowler-cloud/prowler/issues/new?template=bug_report.yml) > > Report or fix issues or bugs. Remember, our community is here to help! If you need guidance, do not hesitate to ask questions in the issues or join our [ Slack workspace](https://goto.prowler.com/slack). ## Setting Up Your Development Environment ### Prerequisites Before proceeding, ensure the following: * Git is installed. * Python 3.10 or higher is installed. * `uv` is installed to manage dependencies. ### Forking the Prowler Repository Fork the Prowler GitHub repository to contribute to Prowler. This allows proposing changes, submitting new features, and fixing bugs. For guidance on forking, refer to the [official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo?tool=webui#forking-a-repository). ### Cloning Your Forked Repository Once your fork is created, clone it using the following commands (replace `` with your GitHub username): ``` git clone https://github.com//prowler cd prowler ``` ### Dependency Management and Environment Isolation To prevent conflicts between environments, we recommend using [`uv`](https://docs.astral.sh/uv/), a fast Python package and project manager. Install it by following the [official instructions](https://docs.astral.sh/uv/getting-started/installation/). ### Installing Dependencies To install all required dependencies, including those needed for development, run: ``` uv sync source .venv/bin/activate ``` ### Running the Local API Development Stack For API development, Prowler provides a Makefile-based local stack in addition to the manual and Docker Compose workflows documented in the API README. PostgreSQL, Valkey, and Neo4j run with Docker Compose, while Django and the Celery worker run natively through `uv`. Before using this method, ensure `docker compose`, `tmux`, and `uv` are installed. This workflow is designed for macOS and should also work on Linux when Docker, `tmux`, and `uv` are available. Windows requires script changes before it can be supported. To start the local API stack, run: ```shell theme={null} make dev ``` This command starts the required services, creates a `tmux` session with panes for the API, worker, and PostgreSQL logs, waits until the API responds, and prints the API URL and log file paths. The API is available at: ```text theme={null} http://localhost:8080/api/v1 ``` Use these commands to manage the stack: ```shell theme={null} make dev-setup # Bootstrap dependencies, migrations, and fixtures make dev-attach # Attach to the tmux session make dev-launch # Start the stack on fixed ports and attach make dev-stop # Stop the tmux session and containers make dev-clean # Remove stopped development containers make dev-wipe # Stop everything and delete local development data make dev-status # Show development container status ``` The UI is not started by this workflow. Start it separately by following the UI development instructions in the `ui/` directory. ### Pre-Commit Hooks This repository uses Git pre-commit hooks managed by the [prek](https://prek.j178.dev/) tool, it is installed with `uv sync`. Next, run the following command in the root of this repository: ```shell theme={null} prek install ``` Successful installation should produce the following output: ```shell theme={null} prek installed at `.git/hooks/pre-commit` ``` > [!WARNING] > > If pre-commit hooks were previously installed, run `prek install --overwrite` to replace the existing hook. Otherwise, both tools will run on each commit. #### Enable TruffleHog as a Pre-Push Hook By default, only `pre-commit` hooks are installed. To enable [`TruffleHog`](https://github.com/trufflesecurity/trufflehog) secret scanning on every push, install the `pre-push` hook type explicitly: ```shell theme={null} prek install --hook-type pre-push ``` Successful installation should produce the following output: ```shell theme={null} prek installed at `.git/hooks/pre-push` ``` Once installed, TruffleHog runs before each push and blocks the operation when verified secrets are detected. ### Code Quality and Security Checks Before merging pull requests, several automated checks and utilities ensure code security and updated dependencies: > [!NOTE] > > These should have been already installed if `uv sync` was already run. * [`bandit`](https://pypi.org/project/bandit/) for code security review. * [`osv-scanner`](https://github.com/google/osv-scanner) and [`dependabot`](https://github.com/features/security) for dependencies. * [`hadolint`](https://github.com/hadolint/hadolint) and [`dockle`](https://github.com/goodwithtech/dockle) for container security. * [`Snyk`](https://docs.snyk.io/integrations/snyk-container-integrations/container-security-with-docker-hub-integration) for container security in Docker Hub. * [`clair`](https://github.com/quay/clair) for container security in Amazon ECR. * [`vulture`](https://pypi.org/project/vulture/), [`flake8`](https://pypi.org/project/flake8/), [`black`](https://pypi.org/project/black/), and [`pylint`](https://pypi.org/project/pylint/) for formatting and best practices. Additionally, ensure the latest version of [`TruffleHog`](https://github.com/trufflesecurity/trufflehog) is installed to scan for sensitive data in the code. Follow the official [installation guide](https://github.com/trufflesecurity/trufflehog?tab=readme-ov-file#floppy_disk-installation) for setup. ### AI-Driven Contributions If you are using AI assistants to help with your contributions, Prowler provides specialized resources to enhance AI-driven development: * **Prowler MCP Server**: The [Prowler MCP Server](/getting-started/products/prowler-mcp) provides AI assistants with access to the entire Prowler ecosystem, including security checks, compliance frameworks, documentation, and more. This enables AI tools to better understand Prowler's architecture and help you create contributions that align with project standards. * **AGENTS.md Files**: Each component of the Prowler monorepo includes an `AGENTS.md` file that contains specific guidelines for AI agents working on that component. These files provide context about project structure, coding standards, and best practices. When working on a specific component, refer to the relevant `AGENTS.md` file (e.g., `prowler/AGENTS.md`, `ui/AGENTS.md`, `api/AGENTS.md`) to ensure your AI assistant follows the appropriate guidelines. * **AI Skills System**: The [AI Skills system](/developer-guide/ai-skills) provides on-demand patterns, templates, and best practices for AI agents. Skills help AI assistants understand Prowler's conventions and generate code that aligns with project standards. The skills are located in the `skills/` directory and are registered in the `AGENTS.md` files. These resources help ensure that AI-assisted contributions maintain consistency with Prowler's codebase and development practices. ### Dependency Management All dependencies are listed in the `pyproject.toml` file. The SDK keeps direct dependencies pinned to exact versions, while `uv.lock` records the full resolved dependency tree and the artifact hashes for every package. Use `uv sync` from the lock file instead of ad-hoc `pip` installs when you need a reproducible environment. For proper code documentation, refer to the following and follow the code documentation practices presented there: [Google Python Style Guide - Comments and Docstrings](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings). > [!NOTE] > > If you encounter issues when committing to the Prowler repository, use the `--no-verify` flag with the `git commit` command. ### Repository Folder Structure The Prowler codebase layout helps quickly locate where to add new features, checks, or integrations. The following is a high-level overview from the root of the repository: ``` prowler/ ├── prowler/ # Main source code for Prowler SDK (CLI, providers, services, checks, compliances, config, etc.) ├── api/ # API server and related code ├── dashboard/ # Local Dashboard extracted from the CLI output ├── ui/ # Web UI components ├── util/ # Utility scripts and helpers ├── tests/ # Prowler SDK test suite ├── docs/ # Documentation, including this guide ├── examples/ # Example output formats for providers and scripts ├── permissions/ # Permission-related files and policies ├── contrib/ # Community-contributed scripts or modules ├── kubernetes/ # Kubernetes deployment files ├── .github/ # GitHub-related files (workflows, issue templates, etc.) ├── pyproject.toml # Python project configuration (uv) ├── uv.lock # uv lock file ├── README.md # Project overview and getting started ├── Makefile # Common development commands ├── Dockerfile # SDK Docker container ├── docker-compose.yml # Prowler Local Server Docker compose └── ... # Other supporting files ``` ## Sending the Pull Request When creating or reviewing a pull request in [Prowler](https://github.com/prowler-cloud/prowler), follow [this template](https://github.com/prowler-cloud/prowler/blob/master/.github/pull_request_template.md) and fill it with the relevant information: * **Context** and **Description** of the change: This will help the reviewers to understand the change and the purpose of the pull request. * **Steps to review**: A detailed description of how to review the change. * **Checklist**: A mandatory checklist of the things that should be reviewed before merging the pull request. ## Contribution Appreciation If you enjoy swag, we'd love to thank you for your contribution with laptop stickers or other Prowler merchandise! To request swag: Share your pull request details in our [Slack workspace](https://goto.prowler.com/slack). You can also reach out to Toni de la Fuente on [Twitter](https://twitter.com/ToniBlyx)—his DMs are open! ## Testing a Pull Request from a Specific Branch To test Prowler from a specific branch (for example, to try out changes from a pull request before it is merged), you can use `pipx` to install directly from GitHub: ```sh theme={null} pipx install "git+https://github.com/prowler-cloud/prowler.git@branch-name" ``` Replace `branch-name` with the name of the branch you want to test. This will install Prowler in an isolated environment, allowing you to try out the changes safely. For more details on testing go to the [Testing section](/developer-guide/unit-testing) of this documentation. # Kubernetes Provider Source: https://docs.prowler.com/developer-guide/kubernetes-details This page details the [Kubernetes](https://kubernetes.io/) provider implementation in Prowler. By default, Prowler will audit all namespaces in the Kubernetes cluster accessible by the configured context. To configure it, see the [In-Cluster Execution](/user-guide/providers/kubernetes/getting-started-k8s#in-cluster-execution) or [Non In-Cluster Execution](/user-guide/providers/kubernetes/getting-started-k8s#non-in-cluster-execution) guides. ## Kubernetes Provider Classes Architecture The Kubernetes provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the Kubernetes-specific implementation, highlighting how the generic provider concepts are realized for Kubernetes in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### `KubernetesProvider` (Main Class) * **Location:** [`prowler/providers/kubernetes/kubernetes_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/kubernetes_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for Kubernetes-specific logic, session management, context and namespace discovery, credential validation, and configuration. * **Key Kubernetes Responsibilities:** * Initializes and manages Kubernetes sessions (supports kubeconfig file or content, context selection, and namespace scoping). * Validates credentials and sets up the Kubernetes identity context. * Loads and manages configuration, mutelist, and fixer settings. * Discovers accessible namespaces and cluster metadata. * Provides properties and methods for downstream Kubernetes service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/kubernetes/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/models.py) * **Purpose:** Define structured data for Kubernetes identity and session info. * **Key Kubernetes Models:** * `KubernetesIdentityInfo`: Holds Kubernetes identity metadata, such as context, cluster, and user. * `KubernetesSession`: Stores the Kubernetes API client and context information. ### `KubernetesService` (Service Base Class) * **Location:** [`prowler/providers/kubernetes/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/lib/service/service.py) * **Purpose:** Abstract base class that all Kubernetes service-specific classes inherit from. This implements the generic service pattern (described in [service page](/developer-guide/services#service-base-class)) specifically for Kubernetes. * **Key Kubernetes Responsibilities:** * Receives a `KubernetesProvider` instance to access session, identity, and configuration. * Manages the Kubernetes API client and context. * Provides a `__threading_call__` method to make API calls in parallel by resource. * Exposes common audit context (`context`, `api_client`, `audit_config`, `fixer_config`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/kubernetes/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/exceptions/exceptions.py) * **Purpose:** Custom exception classes for Kubernetes-specific error handling, such as session, API, and configuration errors. ### Session and Utility Helpers * **Location:** [`prowler/providers/kubernetes/lib/`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/lib/) * **Purpose:** Helpers for argument parsing, mutelist management, and other cross-cutting concerns. ## Specific Patterns in Kubernetes Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/kubernetes/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/kubernetes/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and taking other already implemented services as reference. ### Kubernetes Service Common Patterns * Services communicate with Kubernetes using the Kubernetes Python SDK. See the [official documentation](https://github.com/kubernetes-client/python/blob/master/kubernetes/README.md/). * Every Kubernetes service class inherits from `KubernetesService`, ensuring access to session, identity, configuration, and client utilities. * The constructor (`__init__`) always calls `super().__init__` with the provider object, and initializes resource containers (typically as dictionaries keyed by resource UID or name). * Resource discovery and attribute collection can be parallelized using `self.__threading_call__`. * All Kubernetes resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * Kubernetes API calls are wrapped in try/except blocks, always logging errors. * Additional attributes that cannot be retrieved from the default call should be collected and stored for each resource using dedicated methods and threading. ## Specific Patterns in Kubernetes Checks The Kubernetes checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks in: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/kubernetes/services/rbac/rbac_minimize_wildcard_use_roles/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/kubernetes/services/rbac/rbac_minimize_wildcard_use_roles)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is following the [Kubernetes check implementation documentation](/developer-guide/checks#creating-a-check) and taking other checks as reference. ### Check Report Class The `Check_Report_Kubernetes` class models a single finding for a Kubernetes resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `Check_Report_Kubernetes` extends the base report structure with Kubernetes-specific fields, enabling detailed tracking of the resource, name, and namespace associated with each finding. #### Constructor and Attribute Population When you instantiate `Check_Report_Kubernetes`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its Kubernetes-specific attributes from the resource, using the following logic (in order of precedence): * **`resource_id`**: * Uses `resource.uid` if present. * Otherwise, uses `resource.name` if present. * Defaults to an empty string if none are available. * **`resource_name`**: * Uses `resource.name` if present. * Defaults to an empty string if not available. * **`namespace`**: * Uses `resource.namespace` if present. * Defaults to "cluster-wide" for cluster-scoped resources. If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from which you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} report = Check_Report_Kubernetes( metadata=check_metadata, resource=resource_object ) report.status = "PASS" report.status_extended = "Resource is compliant." ``` # Lighthouse AI Architecture Source: https://docs.prowler.com/developer-guide/lighthouse-architecture This document describes the internal architecture of Prowler Lighthouse AI, enabling developers to understand how components interact and where to add new functionality. > [!NOTE] > > **Looking for user documentation?** See: > > * [Lighthouse AI Overview](/getting-started/products/prowler-lighthouse-ai) - Capabilities and FAQs > * [How Lighthouse AI Works](/user-guide/tutorials/prowler-app-lighthouse) - Configuration and usage > * [Multi-LLM Provider Setup](/user-guide/tutorials/prowler-app-lighthouse-multi-llm) - Provider configuration ## Architecture Overview Lighthouse AI operates as a Langchain-based agent that connects Large Language Models (LLMs) with Prowler security data through the Model Context Protocol (MCP). ![Prowler Lighthouse Architecture](https://mintcdn.com/prowler/dxKr6jfROeYV7A0M/images/lighthouse-architecture.png?fit=max\&auto=format\&n=dxKr6jfROeYV7A0M\&q=85\&s=0660e8227b6a43de0c74b393185709e6) ### Three-Tier Architecture The system follows a three-tier architecture: 1. **Frontend (Next.js)**: Chat interface, message rendering, model selection 2. **API Route**: Request handling, authentication, stream transformation 3. **Langchain Agent**: LLM orchestration, tool calling through MCP ### Request Flow When a user sends a message through the Lighthouse chat interface, the system processes it through several stages: 1. **User Submits a Message**. The chat component (`ui/components/lighthouse/chat.tsx`) captures the user's question (e.g., "What are my critical findings in AWS?") and sends it as an HTTP POST request to the backend API route. 2. **Authentication and Context Assembly**. The API route (`ui/app/api/lighthouse/analyst/route.ts`) validates the user's session, extracts the JWT token (stored via `auth-context.ts`), and gathers context including the tenant's business context and current security posture data (assembled in `data.ts`). 3. **Agent Initialization**. The workflow orchestrator (`ui/lib/lighthouse/workflow.ts`) creates a Langchain agent configured with: * The selected LLM, instantiated through the factory (`llm-factory.ts`) * A system prompt containing available tools and instructions (`system-prompt.ts`) * Two meta-tools (`describe_tool` and `execute_tool`) for accessing Prowler data 4. **LLM Reasoning and Tool Calling**. The agent sends the conversation to the LLM, which decides whether to respond directly or call tools to fetch data. When tools are needed, the meta-tools in `ui/lib/lighthouse/tools/meta-tool.ts` interact with the MCP client (`mcp-client.ts`) to: * First call `describe_tool` to understand the tool's parameters * Then call `execute_tool` to retrieve data from the MCP Server * Continue reasoning with the returned data 5. **Streaming Response**. As the LLM generates its response, the stream handler (`ui/lib/lighthouse/analyst-stream.ts`) transforms Langchain events into UI-compatible messages and streams tokens back to the browser in real-time using Server-Sent Events. The stream includes both text tokens and tool execution events (displayed as "chain of thought"). 6. **Message Rendering**. The frontend receives the stream and renders it through `message-item.tsx` with markdown formatting. Any tool calls that occurred during reasoning are displayed via `chain-of-thought-display.tsx`. ## Frontend Components Frontend components reside in `ui/components/lighthouse/` and handle the chat interface and configuration workflows. ### Core Components | Component | Location | Purpose | | - | - | - | | `chat.tsx` | `ui/components/lighthouse/` | Main chat interface managing message history and input handling | | `message-item.tsx` | `ui/components/lighthouse/` | Individual message rendering with markdown support | | `select-model.tsx` | `ui/components/lighthouse/` | Model and provider selection dropdown | | `chain-of-thought-display.tsx` | `ui/components/lighthouse/` | Displays tool calls and reasoning steps during execution | ### Configuration Components | Component | Location | Purpose | | - | - | - | | `lighthouse-settings.tsx` | `ui/components/lighthouse/` | Settings panel for business context and preferences | | `connect-llm-provider.tsx` | `ui/components/lighthouse/` | Provider connection workflow | | `llm-providers-table.tsx` | `ui/components/lighthouse/` | Provider management table | | `forms/delete-llm-provider-form.tsx` | `ui/components/lighthouse/forms/` | Provider deletion confirmation dialog | ### Supporting Components | Component | Location | Purpose | | - | - | - | | `banner.tsx` / `banner-client.tsx` | `ui/components/lighthouse/` | Status banners and notifications | | `workflow/` | `ui/components/lighthouse/workflow/` | Multi-step configuration workflows | | `ai-elements/` | `ui/components/lighthouse/ai-elements/` | Custom UI primitives for chat interface (input, select, dropdown, tooltip) | ## Library Code Core library code resides in `ui/lib/lighthouse/` and handles agent orchestration, MCP communication, and stream processing. ### Workflow Orchestrator **Location:** `ui/lib/lighthouse/workflow.ts` The workflow module serves as the core orchestrator, responsible for: * Initializing the Langchain agent with system prompt and tools * Loading tenant configuration (default provider, model, business context) * Creating the LLM instance through the factory * Generating dynamic tool listings from available MCP tools ```typescript theme={null} // Simplified workflow initialization export async function initLighthouseWorkflow(runtimeConfig?: RuntimeConfig) { await initializeMCPClient(); const toolListing = generateToolListing(); const systemPrompt = LIGHTHOUSE_SYSTEM_PROMPT_TEMPLATE.replace( "{{TOOL_LISTING}}", toolListing, ); const llm = createLLM({ provider: providerType, model: modelId, credentials, // ... }); return createAgent({ model: llm, tools: [describeTool, executeTool], systemPrompt, }); } ``` ### MCP Client Manager **Location:** `ui/lib/lighthouse/mcp-client.ts` The MCP client manages connections to the Prowler MCP Server using a singleton pattern: * **Connection Management**: Retry logic with configurable attempts and delays * **Tool Discovery**: Fetches available tools from MCP server on initialization * **Authentication Injection**: Automatically adds JWT tokens to `prowler_*` tool calls * **Reconnection**: Supports forced reconnection after server restarts Key constants: * `MAX_RETRY_ATTEMPTS`: 3 connection attempts * `RETRY_DELAY_MS`: 2000ms between retries * `RECONNECT_INTERVAL_MS`: 5 minutes before retry after failure ```typescript theme={null} // Authentication injection for core prowler_ tools (Hub/Docs excluded) private handleBeforeToolCall = ({ name, args }) => { // Only inject auth for prowler_* tools (user-specific data). // The legacy prowler_app_ prefix is also accepted for a resilient rollout. if ( !name.startsWith("prowler_") && !name.startsWith("prowler_app_") ) { return { args }; } const accessToken = getAuthContext(); return { args, headers: { Authorization: `Bearer ${accessToken}` }, }; }; ``` ### Meta-Tools **Location:** `ui/lib/lighthouse/tools/meta-tool.ts` Instead of registering all MCP tools directly with the agent, Lighthouse uses two meta-tools for dynamic tool discovery and execution: | Tool | Purpose | | - | - | | `describe_tool` | Retrieves full schema and parameter details for a specific tool | | `execute_tool` | Executes a tool with provided parameters | This pattern reduces the number of tools the LLM must track while maintaining access to all MCP capabilities. ### Additional Library Modules | Module | Location | Purpose | | - | - | - | | `analyst-stream.ts` | `ui/lib/lighthouse/` | Transforms Langchain stream events to UI message format | | `llm-factory.ts` | `ui/lib/lighthouse/` | Creates LLM instances for OpenAI, Bedrock, and OpenAI-compatible providers | | `system-prompt.ts` | `ui/lib/lighthouse/` | System prompt template with dynamic tool listing injection | | `auth-context.ts` | `ui/lib/lighthouse/` | AsyncLocalStorage for JWT token propagation across async boundaries | | `types.ts` | `ui/lib/lighthouse/` | TypeScript type definitions | | `constants.ts` | `ui/lib/lighthouse/` | Configuration constants and error messages | | `utils.ts` | `ui/lib/lighthouse/` | Message conversion and model parameter extraction | | `validation.ts` | `ui/lib/lighthouse/` | Input validation utilities | | `data.ts` | `ui/lib/lighthouse/` | Current data section generation for context enrichment | ## API Route **Location:** `ui/app/api/lighthouse/analyst/route.ts` The API route handles chat requests and manages the streaming response pipeline: 1. **Request Parsing**: Extracts messages, model, and provider from request body 2. **Authentication**: Validates session and extracts access token 3. **Context Assembly**: Gathers business context and current data 4. **Agent Initialization**: Creates Langchain agent with runtime configuration 5. **Stream Processing**: Transforms agent events to UI-compatible format 6. **Error Handling**: Captures errors with Sentry integration ```typescript theme={null} export async function POST(req: Request) { const { messages, model, provider } = await req.json(); const session = await auth(); if (!session?.accessToken) { return Response.json({ error: "Unauthorized" }, { status: 401 }); } return await authContextStorage.run(accessToken, async () => { const app = await initLighthouseWorkflow(runtimeConfig); const agentStream = app.streamEvents({ messages }, { version: "v2" }); // Transform stream events to UI format const stream = new ReadableStream({ async start(controller) { for await (const streamEvent of agentStream) { // Handle on_chat_model_stream, on_tool_start, on_tool_end, etc. } }, }); return createUIMessageStreamResponse({ stream }); }); } ``` ## Backend Components Backend components handle LLM provider configuration, model management, and credential storage. ### Database Models **Location:** `api/src/backend/api/models.py` | Model | Purpose | | - | - | | `LighthouseProviderConfiguration` | Per-tenant LLM provider credentials (encrypted with Fernet) | | `LighthouseTenantConfiguration` | Tenant-level settings including business context and default provider/model | | `LighthouseProviderModels` | Available models per provider configuration | All models implement Row-Level Security (RLS) for tenant isolation. #### LighthouseProviderConfiguration Stores provider-specific credentials for each tenant: * **provider\_type**: `openai`, `bedrock`, or `openai_compatible` * **credentials**: Encrypted JSON containing API keys or AWS credentials * **base\_url**: Custom endpoint for OpenAI-compatible providers * **is\_active**: Connection validation status #### LighthouseTenantConfiguration Stores tenant-wide Lighthouse settings: * **business\_context**: Optional context for personalized responses * **default\_provider**: Default LLM provider type * **default\_models**: JSON mapping provider types to default model IDs #### LighthouseProviderModels Catalogs available models for each provider: * **model\_id**: Provider-specific model identifier * **model\_name**: Human-readable display name * **default\_parameters**: Optional model-specific parameters ### Background Jobs **Location:** `api/src/backend/tasks/jobs/lighthouse_providers.py` #### check\_lighthouse\_provider\_connection Validates provider credentials by making a test API call: * OpenAI: Lists models via `client.models.list()` * Bedrock: Lists foundation models via `bedrock_client.list_foundation_models()` * OpenAI-compatible: Lists models via custom base URL Updates `is_active` status based on connection result. #### refresh\_lighthouse\_provider\_models Synchronizes available models from provider APIs: * Fetches current model catalog from provider * Filters out non-chat models (DALL-E, Whisper, TTS, embeddings) * Upserts model records in `LighthouseProviderModels` * Removes stale models no longer available **Excluded OpenAI model prefixes:** ```python theme={null} EXCLUDED_OPENAI_MODEL_PREFIXES = ( "dall-e", "whisper", "tts-", "sora", "text-embedding", "text-moderation", # Legacy models "text-davinci", "davinci", "curie", "babbage", "ada", ) ``` ## MCP Server Integration Lighthouse AI communicates with the Prowler MCP Server to access security data. For detailed MCP Server architecture, see [Extending the MCP Server](/developer-guide/mcp-server). ### Tool Namespacing MCP tools are organized into three namespaces based on authentication requirements: | Namespace | Auth Required | Description | | - | - | - | | `prowler_*` | Yes (JWT) | Prowler Cloud, Prowler Private Cloud, and Prowler Local Server tools for findings, providers, scans, resources | | `prowler_hub_*` | No | Security checks catalog, compliance frameworks | | `prowler_docs_*` | No | Documentation search and retrieval | ### Authentication Flow 1. User authenticates with Prowler Local Server, receiving a JWT token 2. Token is stored in session and propagated via `authContextStorage` 3. MCP client injects `Authorization: Bearer ` header for `prowler_*` calls 4. MCP Server validates token and applies RLS filtering ### Tool Execution Pattern The agent uses meta-tools rather than direct tool registration: ``` Agent needs data → describe_tool("prowler_search_findings") → Returns parameter schema → execute_tool with parameters → MCP client adds auth header → MCP Server executes → Results returned to agent → Agent continues reasoning ``` ## Extension Points ### Adding New LLM Providers To add a new LLM provider: 1. **Frontend**: Update `ui/lib/lighthouse/llm-factory.ts` with provider-specific initialization 2. **Backend**: Add provider type to `LighthouseProviderConfiguration.LLMProviderChoices` 3. **Jobs**: Add credential extraction and model fetching in `lighthouse_providers.py` 4. **UI**: Add connection workflow in `ui/components/lighthouse/workflow/` ### Modifying System Prompt The system prompt template lives in `ui/lib/lighthouse/system-prompt.ts`. The `{{TOOL_LISTING}}` placeholder is dynamically replaced with available MCP tools during agent initialization. ### Adding Stream Events To handle new Langchain stream events, modify `ui/lib/lighthouse/analyst-stream.ts`. Current handlers include: * `on_chat_model_stream`: Token-by-token text streaming * `on_chat_model_end`: Model completion with tool call detection * `on_tool_start`: Tool execution started * `on_tool_end`: Tool execution completed ### Adding MCP Tools See [Extending the MCP Server](/developer-guide/mcp-server) for detailed instructions on adding new tools to the Prowler MCP Server. ## Configuration ### Environment Variables | Variable | Description | | - | - | | `PROWLER_MCP_SERVER_URL` | MCP server endpoint (e.g., `https://mcp.prowler.com/mcp`) | ### Database Configuration Provider credentials are stored encrypted in `LighthouseProviderConfiguration`: * **OpenAI**: `{"api_key": "sk-..."}` * **Bedrock**: `{"access_key_id": "...", "secret_access_key": "...", "region": "us-east-1"}` or `{"api_key": "...", "region": "us-east-1"}` * **OpenAI-compatible**: `{"api_key": "..."}` with `base_url` field ### Tenant Configuration Business context and default settings are stored in `LighthouseTenantConfiguration`: ```python theme={null} { "business_context": "Optional organization context for personalized responses", "default_provider": "openai", "default_models": { "openai": "gpt-4o", "bedrock": "anthropic.claude-3-5-sonnet-20240620-v1:0" } } ``` ## Related Documentation > [card] [MCP Server Extension](/developer-guide/mcp-server) > > Adding new tools to the Prowler MCP Server > [card] [Lighthouse AI Overview](/getting-started/products/prowler-lighthouse-ai) > > Capabilities, FAQs, and limitations > [card] [Multi-LLM Setup](/user-guide/tutorials/prowler-app-lighthouse-multi-llm) > > Configuring multiple LLM providers > [card] [How Lighthouse Works](/user-guide/tutorials/prowler-app-lighthouse) > > User-facing architecture and setup guide # LLM Provider Source: https://docs.prowler.com/developer-guide/llm-details This page details the [Large Language Model (LLM)](https://en.wikipedia.org/wiki/Large_language_model) provider implementation in Prowler. The LLM provider enables security testing of language models using red team techniques. By default, Prowler uses the built-in LLM configuration that targets OpenAI models with comprehensive security test suites. To configure it, follow the [LLM getting started guide](/user-guide/providers/llm/getting-started-llm). ## LLM Provider Classes Architecture The LLM provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the LLM-specific implementation, highlighting how the generic provider concepts are realized for LLM security testing in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### Main Class * **Location:** [`prowler/providers/llm/llm_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/llm/llm_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for LLM-specific logic, configuration management, and integration with promptfoo for red team testing. * **Key LLM Responsibilities:** * Initializes and manages LLM configuration using promptfoo. * Validates configuration and sets up the LLM testing context. * Loads and manages red team test configuration, plugins, and target models. * Provides properties and methods for downstream LLM security testing. * Integrates with promptfoo for comprehensive LLM security evaluation. ### Data Models * **Location:** [`prowler/providers/llm/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/llm/models.py) * **Purpose:** Define structured data for LLM output options and configuration. * **Key LLM Models:** * `LLMOutputOptions`: Customizes output filename logic for LLM-specific reporting. ### LLM Security Testing Integration * **Location:** [`prowler/providers/llm/llm_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/llm/llm_provider.py) * **Purpose:** Integrates with promptfoo for comprehensive LLM security testing. * **Key LLM Responsibilities:** * Executes promptfoo red team evaluations against target LLMs. * Processes security test results and converts them to Prowler reports. * Manages test concurrency and progress tracking. * Handles real-time streaming of test results. ### Configuration Management The LLM provider uses promptfoo configuration files to define: * **Target Models**: The LLM models to test (e.g., OpenAI GPT, Anthropic Claude) * **Red Team Plugins**: Security test suites (OWASP, MITRE, NIST, EU AI Act) * **Test Parameters**: Concurrency, test counts, and evaluation criteria ### Default Configuration Prowler includes a comprehensive default LLM configuration that: * Targets OpenAI models by default * Includes multiple security test frameworks (OWASP, MITRE, NIST, EU AI Act) * Provides extensive test coverage for LLM security vulnerabilities * Supports custom configuration for specific testing needs ## Specific Patterns in LLM Security Testing The LLM provider implements security testing through integration with promptfoo, following these patterns: ### Red Team Testing Framework * **Plugin-based Architecture**: Uses promptfoo plugins for different security test categories * **Comprehensive Coverage**: Includes OWASP LLM Top 10, MITRE ATLAS, NIST AI Risk Management, and EU AI Act compliance * **Real-Time Evaluation**: Streams test results as they are generated * **Progress Tracking**: Provides detailed progress information during test execution ### Test Execution Flow 1. **Configuration Loading**: Loads promptfoo configuration with target models and test plugins 2. **Test Generation**: Generates security test cases based on configured plugins 3. **Concurrent Execution**: Runs tests with configurable concurrency limits 4. **Result Processing**: Converts promptfoo results to Prowler security reports 5. **Progress Monitoring**: Tracks and displays test execution progress ### Security Test Categories The LLM provider supports comprehensive security testing across multiple frameworks: * **OWASP LLM Top 10**: Covers prompt injection, data leakage, and model security * **MITRE ATLAS**: Adversarial threat landscape for AI systems * **NIST AI Risk Management**: AI system risk assessment and mitigation * **EU AI Act**: European Union AI regulation compliance * **Custom Tests**: Support for organization-specific security requirements ## Error Handling and Validation The LLM provider includes comprehensive error handling for: * **Configuration Validation**: Ensures valid promptfoo configuration files * **Model Access**: Handles authentication and access issues with target LLMs * **Test Execution**: Manages test failures and timeout scenarios * **Result Processing**: Handles malformed or incomplete test results ## Integration with Prowler Ecosystem The LLM provider seamlessly integrates with Prowler's existing infrastructure: * **Output Formats**: Supports all Prowler output formats (JSON, CSV, HTML, etc.) * **Compliance Frameworks**: Integrates with Prowler's compliance reporting * **Fixer Integration**: Supports automated remediation recommendations * **Dashboard Integration**: Compatible with Prowler Cloud and Prowler Local Server for centralized management # Microsoft 365 (M365) Provider Source: https://docs.prowler.com/developer-guide/m365-details This page details the [Microsoft 365 (M365)](https://www.microsoft.com/en-us/microsoft-365) provider implementation in Prowler. By default, Prowler will audit the Microsoft Entra ID tenant and its supported services. To configure it, follow the [M365 getting started guide](/user-guide/providers/microsoft365/getting-started-m365). *** ## PowerShell Requirements for M365 Checks > **Most Microsoft 365 checks in Prowler require PowerShell, not just the Microsoft Graph API.** * **PowerShell is essential** for retrieving data from Exchange Online, Teams, Defender, Purview, and other M365 services. Many checks cannot be performed using only the Graph API. * **PowerShell 7.4 or higher is required** (7.5 recommended). PowerShell 5.1 and earlier versions are not supported for M365 checks. * **Required modules:** * [ExchangeOnlineManagement](https://www.powershellgallery.com/packages/ExchangeOnlineManagement/3.6.0) (≥ 3.6.0) * [MicrosoftTeams](https://www.powershellgallery.com/packages/MicrosoftTeams/6.6.0) (≥ 6.6.0) * If you use Prowler Cloud or the official containers, PowerShell is pre-installed. For local or pip installations, you must install PowerShell and the modules yourself. See [Authentication: Supported PowerShell Versions](/user-guide/providers/microsoft365/authentication#supported-powershell-versions) and [Needed PowerShell Modules](/user-guide/providers/microsoft365/authentication#required-powershell-modules). * For more details and troubleshooting, see [Use of PowerShell in M365](/user-guide/providers/microsoft365/use-of-powershell). *** ## M365 Provider Classes Architecture The M365 provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the M365-specific implementation, highlighting how the generic provider concepts are realized for M365 in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### `M365Provider` (Main Class) * **Location:** [`prowler/providers/m365/m365_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/m365_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for M365-specific logic, session management, credential validation, region/authority configuration, and identity context. * **Key M365 Responsibilities:** * Initializes and manages M365 sessions (supports Service Principal, environment variables, Azure CLI, browser, and user/password authentication). * Validates credentials and sets up the M365 identity context. * Manages the Microsoft Graph API client and the PowerShell client. * Loads and manages configuration, mutelist, and fixer settings. * Provides properties and methods for downstream M365 service classes to access session, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/m365/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/models.py) * **Purpose:** Define structured data for M365 identity, session, region configuration, and credentials. * **Key M365 Models:** * `M365IdentityInfo`: Holds M365 identity metadata, including tenant ID, domain(s), user, and location. * `M365RegionConfig`: Stores the specific region/authority and API base URL for the tenant. * `M365Credentials`: Represents credentials for authentication (user, password, client ID, client secret, tenant ID, etc.). ### `M365Service` (Service Base Class) * **Location:** [`prowler/providers/m365/lib/service/service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/lib/service/service.py) * **Purpose:** Abstract base class for all M365 service-specific classes. * **Key M365 Responsibilities:** * Receives an `M365Provider` instance to access session, identity, and configuration. * Manages the Microsoft Graph API client for the service. * Initializes a PowerShell client for most services if credentials and identity are available. * Exposes common audit context (`audit_config`, `fixer_config`) to subclasses. ### Exception Handling * **Location:** [`prowler/providers/m365/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/exceptions/exceptions.py) * **Purpose:** Custom exception classes for M365-specific error handling, such as credential, session, region, and argument errors. ### Session and Utility Helpers * **Location:** [`prowler/providers/m365/lib/`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/lib/) * **Purpose:** Helpers for argument parsing, region/authority setup, mutelist management, PowerShell integration, and other cross-cutting concerns. > **Key File: [`m365_powershell.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/lib/powershell/m365_powershell.py)** > > This is the core module for Microsoft 365 PowerShell integration. It manages authentication, session handling, and provides a comprehensive set of methods for interacting with Microsoft Teams, Exchange Online, and Defender policies via PowerShell. > > This module provides secure credential management and authentication using MSAL and PowerShell. It handles automated installation and initialization of required PowerShell modules. The module offers a rich set of methods for retrieving and managing Teams, Exchange, and Defender configurations. It serves as the central component for all M365 provider operations that require PowerShell automation. ## Specific Patterns in M365 Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/m365/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/m365/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is by following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and by taking other already implemented services as reference. ### M365 Service Common Patterns * Services communicate with Microsoft 365 using the Microsoft Graph API **and/or PowerShell**. See the [official documentation](https://learn.microsoft.com/en-us/graph/api/overview) and [PowerShell reference](https://learn.microsoft.com/en-us/powershell/). * Every M365 service class inherits from `M365Service`, ensuring access to session, identity, configuration, and client utilities. * The constructor (`__init__`) always calls `super().__init__` with the provider object, and initializes the Graph client and the PowerShell client. * Resource containers **must** be initialized in the constructor, typically as objects that represent the different settings of the service. * All M365 resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * Microsoft Graph API and PowerShell calls are wrapped in try/except blocks, always logging errors. * To retrieve some data in the services, it is so common that you have to create a new method also in the `m365_powershell.py` file to later be called in the service. ## Specific Patterns in M365 Checks The M365 checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks in: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/m365/services/entra/entra_users_mfa_enabled/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/m365/services/entra/entra_users_mfa_enabled)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is following the [M365 check implementation documentation](/developer-guide/checks#creating-a-check) and by taking other checks as reference. ### Check Report Class The `CheckReportM365` class models a single finding for a Microsoft 365 resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `CheckReportM365` extends the base report structure with M365-specific fields, enabling detailed tracking of the resource, name, and location associated with each finding. #### Constructor and Attribute Population When you instantiate `CheckReportM365`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its M365-specific attributes from the resource, using the following logic (in order of precedence): * **`resource_id`**: A required field that **must** be explicitly set in the constructor to identify the resource being checked. * **`resource_name`**: A required field that **must** be explicitly set in the constructor to provide a human-readable name for the resource. * **`location`**: A required field that can be explicitly set in the constructor to indicate where the resource is located. If not specified, defaults to "global". If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from which you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} report = CheckReportM365( metadata=check_metadata, resource=resource_object ) report.status = "PASS" report.status_extended = "Resource is compliant." ``` # Extending the MCP Server Source: https://docs.prowler.com/developer-guide/mcp-server This guide explains how to extend the Prowler MCP Server with new tools and features. > [!NOTE] > > **New to Prowler MCP Server?** Start with the user documentation: > > * [Overview](/getting-started/products/prowler-mcp) - Key capabilities, use cases, and deployment options > * [Installation](/getting-started/installation/prowler-mcp) - Install locally or use the managed server > * [Configuration](/getting-started/basic-usage/prowler-mcp) - Configure Claude Desktop, Cursor, and other MCP hosts > * [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) - Complete list of all available tools ## Introduction The Prowler MCP Server brings the entire Prowler ecosystem to AI assistants through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It enables seamless integration with AI tools like Claude Desktop, Cursor, and other MCP clients. The server follows a modular architecture with three independent sub-servers: | Sub-Server | Tool Prefix | Auth Required | Description | | - | - | - | - | | Prowler | `prowler_` | Yes | Full access to Prowler Cloud, Prowler Private Cloud, and Prowler Local Server features | | Prowler Hub | `prowler_hub_` | No | Security checks catalog with **over 2,000 checks**, fixers, and **70+ compliance frameworks** | | Prowler Documentation | `prowler_docs_` | No | Full-text search and retrieval of official documentation | > [!NOTE] > > The core Prowler sub-server is served under the `prowler_` tool prefix, while its source lives in the `prowler_app/` module for historical reasons. Tool names use the prefix; import paths use the module. > [!NOTE] > > For a complete list of tools and their descriptions, see the [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools). ## Architecture Overview The MCP Server architecture is illustrated in the [Overview documentation](/getting-started/products/prowler-mcp#mcp-server-architecture). AI assistants connect through the MCP protocol to access Prowler's three main components. ### Server Structure The main server orchestrates three sub-servers with prefixed namespacing: ``` mcp_server/prowler_mcp_server/ ├── server.py # Main orchestrator ├── main.py # CLI entry point ├── prowler_hub/ ├── prowler_app/ │ ├── tools/ # Tool implementations │ ├── models/ # Pydantic models │ └── utils/ # API client, auth, loader └── prowler_documentation/ ``` ### Tool Registration Patterns The MCP Server uses two patterns for tool registration: 1. **Direct Decorators** (Prowler Hub/Docs): Tools are registered using `@mcp.tool()` decorators 2. **Auto-Discovery** (`prowler_app`): All public methods of `BaseTool` subclasses are auto-registered ## Adding Tools to the `prowler_app` Sub-Server ### Step 1: Create the Tool Class Create a new file or add to an existing file in `prowler_app/tools/`: ```python theme={null} # prowler_app/tools/new_feature.py from typing import Any from pydantic import Field from prowler_mcp_server.prowler_app.models.new_feature import ( FeatureListResponse, DetailedFeature, ) from prowler_mcp_server.prowler_app.tools.base import BaseTool class NewFeatureTools(BaseTool): """Tools for managing new features.""" async def list_features( self, status: str | None = Field( default=None, description="Filter by status (active, inactive, pending)" ), page_size: int = Field( default=50, description="Number of results per page (1-100)" ), ) -> dict[str, Any]: """List all features with optional filtering. Returns a lightweight list of features optimized for LLM consumption. Use get_feature for complete information about a specific feature. """ # Validate parameters self.api_client.validate_page_size(page_size) # Build query parameters params: dict[str, Any] = {"page[size]": page_size} if status: params["filter[status]"] = status # Make API request clean_params = self.api_client.build_filter_params(params) response = await self.api_client.get("/api/v1/features", params=clean_params) # Transform to LLM-friendly format return FeatureListResponse.from_api_response(response).model_dump() async def get_feature( self, feature_id: str = Field(description="The UUID of the feature"), ) -> dict[str, Any]: """Get detailed information about a specific feature. Returns complete feature details including configuration and metadata. """ response = await self.api_client.get(f"/api/v1/features/{feature_id}") return DetailedFeature.from_api_response(response["data"]).model_dump() ``` There is no `try`/`except` here on purpose. A failed request raises, and [Error Handling](#error-handling) explains what turns that raise into a message the agent can act on. ### Step 2: Create the Models Create corresponding models in `prowler_app/models/`: ```python theme={null} # prowler_app/models/new_feature.py from typing import Any from pydantic import Field from prowler_mcp_server.prowler_app.models.base import MinimalSerializerMixin class SimplifiedFeature(MinimalSerializerMixin): """Lightweight feature for list operations.""" id: str = Field(description="Unique feature identifier") name: str = Field(description="Feature name") status: str = Field(description="Current status") @classmethod def from_api_response(cls, data: dict[str, Any]) -> "SimplifiedFeature": """Transform API response to simplified format.""" attributes = data.get("attributes", {}) return cls( id=data["id"], name=attributes["name"], status=attributes["status"], ) class DetailedFeature(SimplifiedFeature): """Extended feature with complete details.""" description: str | None = Field(default=None, description="Feature description") configuration: dict[str, Any] | None = Field(default=None, description="Configuration") created_at: str = Field(description="Creation timestamp") updated_at: str = Field(description="Last update timestamp") @classmethod def from_api_response(cls, data: dict[str, Any]) -> "DetailedFeature": """Transform API response to detailed format.""" attributes = data.get("attributes", {}) return cls( id=data["id"], name=attributes["name"], status=attributes["status"], description=attributes.get("description"), configuration=attributes.get("configuration"), created_at=attributes["created_at"], updated_at=attributes["updated_at"], ) class FeatureListResponse(MinimalSerializerMixin): """Response wrapper for feature list operations.""" count: int = Field(description="Total number of features") features: list[SimplifiedFeature] = Field(description="List of features") @classmethod def from_api_response(cls, response: dict[str, Any]) -> "FeatureListResponse": """Transform API response to list format.""" data = response.get("data", []) features = [SimplifiedFeature.from_api_response(item) for item in data] return cls(count=len(features), features=features) ``` ### Step 3: Verify Auto-Discovery No manual registration is needed. The `tool_loader.py` automatically discovers and registers all `BaseTool` subclasses. Verify your tool is loaded by checking the server logs: ``` INFO - Auto-registered 2 tools from NewFeatureTools INFO - Loaded and registered: NewFeatureTools ``` ## Adding Tools to Prowler Hub/Docs For Prowler Hub or Documentation tools, use the `@mcp.tool()` decorator directly: ```python theme={null} # prowler_hub/server.py from fastmcp import FastMCP hub_mcp_server = FastMCP("prowler-hub") @hub_mcp_server.tool() async def get_new_artifact( artifact_id: str, ) -> dict: """Fetch a specific artifact from Prowler Hub. Args: artifact_id: The unique identifier of the artifact Returns: Dictionary containing artifact details """ response = prowler_hub_client.get(f"/artifact/{artifact_id}") response.raise_for_status() return response.json() ``` ## Model Design Patterns ### MinimalSerializerMixin All models should use `MinimalSerializerMixin` to optimize responses for LLM consumption: ```python theme={null} from prowler_mcp_server.prowler_app.models.base import MinimalSerializerMixin class MyModel(MinimalSerializerMixin): """Model that excludes empty values from serialization.""" required_field: str optional_field: str | None = None # Excluded if None empty_list: list = [] # Excluded if empty ``` This mixin automatically excludes: * `None` values * Empty strings * Empty lists * Empty dictionaries ### Two-Tier Model Pattern Use two-tier models for efficient responses: * **Simplified**: Lightweight models for list operations * **Detailed**: Extended models for single-item retrieval ```python theme={null} class SimplifiedItem(MinimalSerializerMixin): """Use for list operations - minimal fields.""" id: str name: str status: str class DetailedItem(SimplifiedItem): """Use for get operations - extends simplified with details.""" description: str | None = None configuration: dict | None = None created_at: str updated_at: str ``` ### Factory Method Pattern Always implement `from_api_response()` for API transformation: ```python theme={null} @classmethod def from_api_response(cls, data: dict[str, Any]) -> "MyModel": """Transform API response to model. This method handles the JSON:API format used by Prowler API, extracting attributes and relationships as needed. """ attributes = data.get("attributes", {}) return cls( id=data["id"], name=attributes["name"], # ... map other fields ) ``` ## API Client Usage The `ProwlerAPIClient` is a singleton that handles authentication and HTTP requests: ```python theme={null} class MyTools(BaseTool): async def my_tool(self) -> dict: # GET request response = await self.api_client.get("/api/v1/endpoint", params={"key": "value"}) # POST request response = await self.api_client.post( "/api/v1/endpoint", json_data={"data": {"type": "items", "attributes": {...}}} ) # PATCH request response = await self.api_client.patch( f"/api/v1/endpoint/{id}", json_data={"data": {"attributes": {...}}} ) # DELETE request response = await self.api_client.delete(f"/api/v1/endpoint/{id}") ``` ### Helper Methods The API client provides useful helper methods: ```python theme={null} # Validate page size (1-1000) self.api_client.validate_page_size(page_size) # Normalize date range with max days limit date_range = self.api_client.normalize_date_range(date_from, date_to, max_days=2) # Build filter parameters (handles type conversion) clean_params = self.api_client.build_filter_params({ "filter[status]": "active", "filter[severity__in]": ["high", "critical"], # Converts to comma-separated "filter[muted]": True, # Converts to "true" }) # Poll async task until completion result = await self.api_client.poll_task_until_complete( task_id=task_id, timeout=60, poll_interval=1.0 ) ``` ## Best Practices ### Tool Docstrings Tool docstrings become the description that is going to be read by the LLM. Provide clear usage instructions and common workflows: ```python theme={null} async def search_items(self, status: str = Field(...)) -> dict: """Search items with advanced filtering. Returns a lightweight list optimized for LLM consumption. Use get_item for complete details about a specific item. Common workflows: - Find critical items: status="critical" - Find recent items: Use date_from parameter """ ``` ### Error Handling **Raise, never return.** A returned `{"error": ...}` dict is reported to the client as `isError: false` -- a *successful* tool call whose payload happens to mention a failure. Clients and models read that as success. A raised exception becomes a spec-correct tool execution error instead. The common case therefore needs no handler at all: ```python theme={null} async def get_item(self, item_id: str) -> dict: response = await self.api_client.get(f"/api/v1/items/{item_id}") return DetailedItem.from_api_response(response["data"]).model_dump() ``` `prowler_mcp_server/lib/errors.py` classifies the failures every tool shares -- a rejected credential, a missing permission, a rate limit, an outage, an unreachable API, a bad argument -- and gives each one a message that says what went wrong and what to do about it. Anything it does not recognise is masked, because `mask_error_details=True` is set on every sub-server and upstream response bodies must never be replayed into a model's context. Three ways to raise, in the order to reach for them: ```python theme={null} from fastmcp.exceptions import ToolError from prowler_mcp_server.lib.errors import InvalidArgument # 1. An argument this server rejected before any request went out. The message # is repeated to the agent verbatim, so write it for one to read. if not 1 <= page_size <= 1000: raise InvalidArgument("page_size must be between 1 and 1000.") # 2. A request the API answered or never answered: let it propagate untouched. # `ProwlerAPIError` and `ProwlerAPIUnreachable` are what the classifier keys # on, and the second one is what stops a retry from duplicating a write. response = await self.api_client.get(f"/api/v1/items/{item_id}") data = response["data"] # 3. A sentence the classifier cannot know -- a resource name, a precondition, # the next tool to call. NOTE the absent `from` clause: it is what marks the # message as already final. With `from e` the classifier would replace it. if not data: raise ToolError( f"No item with the ID {item_id!r} exists. Use prowler_list_items to " "find a valid one." ) ``` The one thing that still *returns* rather than raises is a write whose outcome is genuinely unknown. `prowler_send_findings_to_jira` is the worked example: work items are created one at a time and Prowler cannot delete them, so a dispatch that stopped halfway answers with a result object carrying `safe_to_retry: false`. "This may have been applied" is a fact about the world, not an error, and squashing it into one loses the only thing that stops a retry from duplicating the write. ### Parameter Descriptions Use Pydantic `Field()` with clear descriptions. This also helps LLMs understand the purpose of each parameter, so be as descriptive as possible: ```python theme={null} async def list_items( self, severity: list[str] = Field( default=[], description="Filter by severity levels (critical, high, medium, low)" ), status: str | None = Field( default=None, description="Filter by status (PASS, FAIL, MANUAL)" ), page_size: int = Field( default=50, description="Results per page" ), ) -> dict: ``` ## Development Commands ```bash theme={null} # Navigate to MCP server directory cd mcp_server # Run in STDIO mode (default) uv run prowler-mcp # Run in HTTP mode uv run prowler-mcp --transport http --host 0.0.0.0 --port 8000 # Run with environment variables PROWLER_API_KEY="pk_xxx" uv run prowler-mcp ``` For complete installation and deployment options, see: * [Installation Guide](/getting-started/installation/prowler-mcp#from-source-development) - Development setup instructions * [Configuration Guide](/getting-started/basic-usage/prowler-mcp) - MCP client configuration For development I recommend to use the [Model Context Protocol Inspector](https://github.com/modelcontextprotocol/inspector) as MCP client to test and debug your tools. ## Testing Tests live in `mcp_server/tests/`, mirroring the source tree, and use the `test_*.py` prefix (the same convention as the API, not the SDK's `*_test.py` suffix). From `mcp_server/`: ```bash theme={null} cd mcp_server uv run pytest # Whole suite uv run pytest tests/prowler_app/models # One area uv run pytest --cov=./prowler_mcp_server # With coverage ``` From the repository root: ```bash theme={null} make test-mcp # Runs the MCP suite exactly as CI does ``` Async tests need no marker — `asyncio_mode` is set to `auto`. ### Reading the Coverage Numbers > [!WARNING] > > Coverage here has a high floor that means nothing. `coverage.py` measures > *statements*, and in a Pydantic model module nearly every statement is a class-body > field declaration that runs at **import** time. `prowler_app/server.py` imports > every tool module — and therefore every model module — when it is first imported, > so all of those declarations execute and count as covered before a single test runs. > > Importing the package and executing no tests at all already reports **36% overall**, > with individual model modules between 54% and 84%. A model module sitting at \~68% > with no tests written for it has **none** of its behaviour covered: the covered lines > are its imports, `class` statements and `Field(...)` declarations, and the missing > ranges are its `from_api_response()` bodies. > > Judge a module against that import-only floor, not against zero, and do not set a > Codecov target from the raw total. ### Shared Fixtures All fixtures live in `mcp_server/tests/conftest.py`. Three are autouse and apply to every test: the environment is pinned to deterministic values, real socket connections are blocked, and the API client singleton registry is snapshotted and restored. | Fixture | What it gives you | | - | - | | `mock_api_client` | The API client singleton with its transport mocked. The workhorse. | | `mock_router` | Route registry and request recorder | | `mcp_root_server` | The mounted root server, for in-memory client tests | | `health_client` | Starlette `TestClient` for the `/health` route | | `http_request_headers` | Injects request headers for HTTP-transport auth tests | | `hub_router` / `docs_router` | Mock the Hub and Docs sub-servers' sync HTTP clients | | `api_client` / `isolated_api_client` | The live singleton / a freshly-constructed one | Helpers live in `mcp_server/tests/helpers/`: JSON:API document builders (`jsonapi.py`), the `MockRouter` (`http.py`), tool-contract assertions (`assertions.py`) and fake credentials (`tokens.py`). ### Writing a Tool Test Drive tools through an in-memory MCP client, and open the client inside the test — FastMCP warns that holding a client in a fixture causes event-loop problems. ```python theme={null} from fastmcp import Client from tests.helpers.jsonapi import jsonapi_collection, jsonapi_resource FINDING_ATTRIBUTES = { "uid": "prowler-aws-s3_bucket_public_access-123456789012-us-east-1-my-bucket", "status": "FAIL", "severity": "high", "status_extended": "S3 bucket my-bucket is publicly accessible.", "delta": "new", "muted": False, "muted_reason": None, "check_metadata": {"checkid": "s3_bucket_public_access"}, } async def test_search_without_dates_queries_the_latest_scan_endpoint( mcp_root_server, mock_api_client, mock_router ): """With no date range the tool targets the cheaper `/findings/latest`.""" mock_router.add( "GET", "/api/v1/findings/latest", json=jsonapi_collection( [jsonapi_resource("findings", "f1", FINDING_ATTRIBUTES)] ), ) async with Client(mcp_root_server) as client: result = await client.call_tool("prowler_search_security_findings", {}) assert result.data["findings"][0]["check_id"] == "s3_bucket_public_access" assert mock_router.paths() == ["GET /api/v1/findings/latest"] ``` The exemplar suite covers `findings` end to end — `tests/prowler_app/models/test_findings.py` and `tests/prowler_app/tools/test_findings.py`. It is deliberately one feature across both layers rather than a scattering of unrelated samples, and `findings` is the feature that exercises the whole foundation: two-tier models, nested sub-models, both relationship shapes, endpoint switching on a date range, list-to-CSV filter encoding, and a tool that returns prose instead of a model. Note the two files share a name. That is why `__init__.py` is required in every `tests/` subdirectory here — without it they would collide on import. > [!WARNING] > > Tool parameters are declared with pydantic `Field(default=...)`, and only FastMCP's > tool wrapper resolves those defaults. Calling a tool method directly with an > argument omitted leaves it as a raw `FieldInfo` object, which is truthy — so a > filter such as `if email:` silently builds a query out of the `FieldInfo` repr. > Call tools through the client, or pass every argument explicitly. ### Why the API Key Is Pinned, Not Stripped `prowler_app/server.py` builds every tool at import time. Constructing a tool reaches `ProwlerAppAuth`, which raises when `PROWLER_API_KEY` is missing, and `load_all_tools` swallows that error per tool class. The result is that the whole `prowler_*` namespace registers **zero** tools while the server still logs "Successfully mounted Prowler tools server". The suite therefore pins a fake key in `[tool.pytest_env]`, which is applied before any test module is imported, and `tests/test_server.py` asserts each namespace is non-empty so this failure can never return silently. > [!NOTE] > > `ProwlerAppAuth` resolves `PROWLER_MCP_TRANSPORT_MODE` and `API_BASE_URL` in its > default arguments, which Python evaluates once at module import. `monkeypatch.setenv` > cannot change them — pass `mode=` and `base_url=` explicitly in auth tests. For the full set of rules and templates, see the [`prowler-test-mcp` skill](https://github.com/prowler-cloud/prowler/blob/master/skills/prowler-test-mcp/SKILL.md) and the [official FastMCP testing guide](https://gofastmcp.com/development/tests). ## Related Documentation > [card] [MCP Server Overview](/getting-started/products/prowler-mcp) > > Key capabilities, use cases, and deployment options > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Complete reference of all available tools > [card] [Prowler Hub](/getting-started/products/prowler-hub) > > Security checks and compliance frameworks catalog > [card] [Lighthouse AI](/getting-started/products/prowler-lighthouse-ai) > > AI-powered security analyst ## Additional Resources * [MCP Protocol Specification](https://modelcontextprotocol.io) - Model Context Protocol details * [Prowler API Documentation](https://api.prowler.com/api/v1/docs) - API reference * [Prowler Hub API](https://hub.prowler.com/api/docs) - Hub API reference * [GitHub Repository](https://github.com/prowler-cloud/prowler) - Source code # Create a Custom Output Format Source: https://docs.prowler.com/developer-guide/outputs ## Introduction Prowler supports multiple output formats, allowing users to tailor findings presentation to their needs. Custom output formats are valuable when integrating Prowler with third-party tools, generating specialized reports, or adapting data for specific workflows. By defining a custom output format, users can refine how findings are structured, extracting and displaying only the most relevant information. * Output Organization in Prowler Prowler outputs are managed within the `/lib/outputs` directory. Each format—such as JSON, CSV, HTML, SARIF—is implemented as a Python class. * Outputs are generated based on scan findings, which are stored as structured dictionaries containing details such as: * Resource IDs * Severities * Descriptions * Other relevant metadata * Creation Guidelines Refer to the [Prowler Developer Guide](https://docs.prowler.com/projects/prowler-open-source/en/latest/) for insights into Prowler’s architecture and best practices for creating custom outputs. * Identify the most suitable integration method for the output being targeted. ## Steps to Create a Custom Output Format ### Schema * Output Class: * The class must inherit from `Output`. Review the [Output Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/outputs/output.py). * Create a class that encapsulates the required attributes and methods for interacting with the target platform. Below the code for the `CSV` class is presented: ```python title="CSV Class" theme={null} class CSV(Output): def transform(self, findings: List[Finding]) -> None: """Transforms the findings into the CSV format. Args: findings (list[Finding]): a list of Finding objects """ ... ``` * Transform Method: * This method will transform the findings provided by Prowler to a specific format. #### Method Implementation The following example demonstrates the `transform` method for the `CSV` class: ```python title="Transform" theme={null} def transform(self, findings: List[Finding]) -> None: """Transforms the findings into the CSV format. Args: findings (list[Finding]): a list of Finding objects """ try: for finding in findings: finding_dict = {} finding_dict["AUTH_METHOD"] = finding.auth_method finding_dict["TIMESTAMP"] = finding.timestamp finding_dict["ACCOUNT_UID"] = finding.account_uid finding_dict["ACCOUNT_NAME"] = finding.account_name finding_dict["ACCOUNT_EMAIL"] = finding.account_email finding_dict["ACCOUNT_ORGANIZATION_UID"] = ( finding.account_organization_uid ) finding_dict["ACCOUNT_ORGANIZATION_NAME"] = ( finding.account_organization_name ) finding_dict["ACCOUNT_TAGS"] = unroll_dict( finding.account_tags, separator=":" ) finding_dict["FINDING_UID"] = finding.uid finding_dict["PROVIDER"] = finding.metadata.Provider finding_dict["CHECK_ID"] = finding.metadata.CheckID finding_dict["CHECK_TITLE"] = finding.metadata.CheckTitle finding_dict["CHECK_TYPE"] = unroll_list(finding.metadata.CheckType) finding_dict["STATUS"] = finding.status.value finding_dict["STATUS_EXTENDED"] = finding.status_extended finding_dict["MUTED"] = finding.muted finding_dict["SERVICE_NAME"] = finding.metadata.ServiceName finding_dict["SUBSERVICE_NAME"] = finding.metadata.SubServiceName finding_dict["SEVERITY"] = finding.metadata.Severity.value finding_dict["RESOURCE_TYPE"] = finding.metadata.ResourceType finding_dict["RESOURCE_UID"] = finding.resource_uid finding_dict["RESOURCE_NAME"] = finding.resource_name finding_dict["RESOURCE_DETAILS"] = finding.resource_details finding_dict["RESOURCE_TAGS"] = unroll_dict(finding.resource_tags) finding_dict["PARTITION"] = finding.partition finding_dict["REGION"] = finding.region finding_dict["DESCRIPTION"] = finding.metadata.Description finding_dict["RISK"] = finding.metadata.Risk finding_dict["RELATED_URL"] = finding.metadata.RelatedUrl finding_dict["ADDITIONAL_URLS"] = unroll_list(finding.metadata.AdditionalURLs) finding_dict["REMEDIATION_RECOMMENDATION_TEXT"] = ( finding.metadata.Remediation.Recommendation.Text ) finding_dict["REMEDIATION_RECOMMENDATION_URL"] = ( finding.metadata.Remediation.Recommendation.Url ) finding_dict["REMEDIATION_CODE_NATIVEIAC"] = ( finding.metadata.Remediation.Code.NativeIaC ) finding_dict["REMEDIATION_CODE_TERRAFORM"] = ( finding.metadata.Remediation.Code.Terraform ) finding_dict["REMEDIATION_CODE_CLI"] = ( finding.metadata.Remediation.Code.CLI ) finding_dict["REMEDIATION_CODE_OTHER"] = ( finding.metadata.Remediation.Code.Other ) finding_dict["COMPLIANCE"] = unroll_dict( finding.compliance, separator=": " ) finding_dict["CATEGORIES"] = unroll_list(finding.metadata.Categories) finding_dict["DEPENDS_ON"] = unroll_list(finding.metadata.DependsOn) finding_dict["RELATED_TO"] = unroll_list(finding.metadata.RelatedTo) finding_dict["NOTES"] = finding.metadata.Notes finding_dict["PROWLER_VERSION"] = finding.prowler_version self._data.append(finding_dict) except Exception as error: logger.error( f"{error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) ``` * Batch Write Data To File Method: * This method will write the modeled object to a file. #### Method Implementation The following example demonstrates the `batch_write_data_to_file` method for the `CSV` class: ```python title="Batch Write Data To File" theme={null} def batch_write_data_to_file(self) -> None: """Writes the findings to a file using the CSV format using the `Output._file_descriptor`.""" try: if ( getattr(self, "_file_descriptor", None) and not self._file_descriptor.closed and self._data ): csv_writer = DictWriter( self._file_descriptor, fieldnames=self._data[0].keys(), delimiter=";", ) csv_writer.writeheader() for finding in self._data: csv_writer.writerow(finding) self._file_descriptor.close() except Exception as error: logger.error( f"{error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) ``` ### Integrating the Custom Output Format into Prowler Once the custom output format is created, it must be integrated into Prowler to ensure compatibility with the existing architecture. #### Reviewing Current Supported Outputs Before implementing the new output format, examine the usage of currently supported formats to understand their structure and integration approach. Example: CSV Output Creation in Prowler Below is an example of how Prowler generates and processes CSV output within its [codebase](https://github.com/prowler-cloud/prowler/blob/master/prowler/__main__.py): ```python title="CSV creation" theme={null} if mode == "csv": csv_output = CSV( findings=finding_outputs, create_file_descriptor=True, file_path=f"{filename}{csv_file_suffix}", ) generated_outputs["regular"].append(csv_output) # Write CSV Finding Object to file. csv_output.batch_write_data_to_file() ``` ### Testing * Verify that Prowler’s findings are accurately typed in the desired output format. * Error Handling – Simulate edge cases to assess robustness and failure recovery mechanisms. ### Documentation * Ensure the following elements are included: * Setup Instructions – List all necessary dependencies and installation steps. * Configuration details. * Example Use Cases – Provide practical scenarios demonstrating functionality. * Troubleshooting Guide – Document common issues and resolution steps. * Comprehensive and clear documentation improves maintainability and simplifies onboarding of new users. # Prowler Providers Source: https://docs.prowler.com/developer-guide/provider ## Introduction Providers form the backbone of Prowler, enabling security assessments across various cloud environments. A provider is any platform or service that offers resources, data, or functionality that can be audited for security and compliance. This includes: * Cloud Infrastructure Providers (like Amazon Web Services, Microsoft Azure, and Google Cloud) * Software as a Service (SaaS) Platforms (like Microsoft 365) * Development Platforms (like GitHub) * Container Orchestration Platforms (like Kubernetes) * Database-as-a-Service Platforms (like MongoDB Atlas) For providers supported by Prowler, refer to [Prowler Hub](https://hub.prowler.com/). > [!WARNING] > > There are some custom providers added by the community, like [NHN Cloud](https://www.nhncloud.com/), that are not maintained by the Prowler team, but can be used in the Prowler CLI. The main purpose of this documentation is to guide you through creating a new provider and integrating it not only in the CLI, but also in the API and UI. Non official providers can be checked directly at the [Prowler GitHub repository](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers). *** ## Provider Types in Prowler Prowler supports several types of providers, each with its own implementation pattern and use case. Understanding these differences is key to designing your provider correctly. ### Classifying Your Provider Before implementing a new provider, you need to determine which type it belongs to. This classification will guide your implementation approach and help you choose the right patterns and libraries. #### Decision Criteria Once you have decided the provider you want or need to add to Prowler, the next step is to study how to retrieve data from it. Based on that, the provider will fall into one of the following types: SDK, API or Tool/Wrapper (maybe in the future there will be new types but for now these are the only ones). **Choose SDK Provider if:** * The target platform/service has an **official Python SDK** available * The target platform/service has a **non-official Python SDK** available but it's been updated and maintained * You need to support **multiple authentication methods** (profiles, service principals, IAM roles, etc.) * The SDK provides **built-in session management**, retry logic, and error handling * You want to leverage **SDK-specific features** like credential chaining, role assumption, etc * The platform is a **major cloud provider** (AWS, Azure, GCP, etc.) or has mature SDK support **Choose API Provider if:** * The target platform has a **REST API** but **no official Python SDK** * The target platform has a **non-official Python SDK** available but it's not updated and maintained * You need to implement **custom authentication flows** (OAuth, token-based, etc.) * The platform is a **custom or community service** without official SDK support * You want to use **standard HTTP libraries** like `requests` for API calls * The platform exposes **well-documented REST endpoints** but lacks SDK tooling **Choose Tool/Wrapper Provider if:** * You're integrating a **third-party security tool** or library * The tool provides **scanning capabilities** that need to be adapted to Prowler's interface * You don't need **authentication or session management** (the tool handles this) * You need to **map tool arguments** and **convert outputs** to Prowler's format **Special Case - Hybrid Providers:** * Some providers may **combine multiple approaches** (e.g., SDK + Tool wrapper, SDK + API, etc.) * Example: M365 uses **msgraph SDK** for authentication and some checks, and **PowerShell wrapper** for other checks that the SDK doesn't support * These require **custom implementation patterns** that blend different provider types #### Classification Examples | Provider | Type | Reasoning | | - | - | - | | AWS | SDK | Official boto3 SDK, multiple auth methods, mature ecosystem | | Azure | SDK | Official azure-identity SDK, service principals, managed identity | | GCP | SDK | Official google-auth SDK, service accounts, ADC support | | Kubernetes | SDK | Official kubernetes SDK, service accounts, ADC support | | NHN Cloud | API | Custom REST API, no official SDK, community provider | | MongoDB Atlas | API | Custom REST API, no official SDK | | IAC | Tool | Third-party security tool that uses trivy, no auth needed, output conversion | | M365 | Hybrid | Combines msgraph SDK for auth + PowerShell wrapper for operations | | GitHub | Hybrid | Non-Official PyGithub SDK but it's been updated and maintained + Official graphql API requests | #### Questions to Ask Yourself **1. Does the platform have an official Python SDK?** * Yes → Consider SDK Provider * No → Continue to question 2 **2. Does the platform have a non-official Python SDK?** * Yes → Then if the SDK is updated and maintained, consider SDK Provider, otherwise continue to question 3. * No → Continue to question 3 **3. Is this a third-party security tool or library?** * Yes → Consider Tool/Wrapper Provider * No → Continue to question 4 **4. Does the platform expose a REST API?** * Yes → Consider API Provider * No → You may need a custom approach ![FlowChart Decision](https://mintcdn.com/prowler/u7I-Csh7ps23rGWs/img/provider-decision-tree.png?fit=max\&auto=format\&n=u7I-Csh7ps23rGWs\&q=85\&s=d9cf953cd5a28a5c3a13343755bc4b1a) #### Implementation Complexity * **SDK Providers**: Low complexity. You have mature examples like AWS, Azure, GCP, Kubernetes, etc. that you can leverage to implement your provider. * **API Providers**: Medium complexity. You need to implement the authentication and session management, and the API calls to the provider. You now have NHN and MongoDB Atlas as example to follow. * **Tool/Wrapper Providers**: High complexity. You need to implement the argument/output mapping to the provider and handle problems that the tool/wrapper may have. You now have IAC and the PowerShell wrapper as example to follow. * **Hybrid Providers**: High complexity. You need to "customize" your provider, mixing the other types of providers to achieve the desired result. You have M365 (msgraph SDK + PowerShell wrapper) and GitHub (PyGithub SDK + graphql API requests) as examples. ### Determining Regional vs Non-Regional Architecture After classifying your provider type, the next critical decision is determining whether your provider operates with **regional concepts** or is **global/non-regional**. This decision fundamentally affects how your provider and services are structured and executed. #### Regional Providers Regional providers operate across multiple geographic locations and require region-specific resource discovery and iteration. **Examples:** * **AWS**: Has regions like `us-east-1`, `eu-west-1`, `ap-southeast-2` * **Azure**: Has regions like `East US`, `West Europe`, `Australia East` * **GCP**: Has regions like `us-central1`, `europe-west1`, `asia-southeast1` **Implementation Requirements:** * Must implement region discovery and iteration * Services must be instantiated per region or handle multi-region data * Checks must execute across all available/specified regions * Resource ARNs/IDs must include region information * Region-specific client initialization **Execution Pattern:** ```python theme={null} # Regional provider execution pattern for region in provider.get_regions(): regional_client = service.get_regional_client(region) regional_resources = regional_client.discover_resources() # Process regional resources ``` #### Non-Regional (Global) Providers Non-regional providers operate globally without geographic partitioning. **Examples:** * **GitHub**: Repositories, organizations are global concepts * **M365**: Tenants operate globally across Microsoft datacenters * **Kubernetes**: Clusters are independent units without regional concepts **Implementation Requirements:** * Single global client/session * No region iteration required * Global resource discovery * Simpler resource identification (no region in ARNs/IDs) * Single audit execution **Execution Pattern:** ```python theme={null} # Non-regional provider execution pattern global_client = service.get_client() global_resources = global_client.discover_resources() # Process all resources in single iteration ``` #### Decision Matrix | Aspect | Regional Provider | Non-Regional Provider | | - | - | - | | **Client Init** | Per-region clients | Single global client | | **Resource Discovery** | Iterate through regions | Single discovery call | | **Resource ARN/ID** | Include region | Global identifier/None | | **Audit Execution** | Multi-region loops | Single execution | | **Service Architecture** | Region-aware services | Global services | | **Performance** | Parallelizable by region | Linear execution | #### Region Discovery Region discovery is the process of getting the list of regions that are available for the account. This is done by the provider and is stored in the `prowler/providers//lib/regions/_regions.py` file. ```python theme={null} # File: prowler/providers/aws/aws_provider.py def get_aws_enabled_regions(self, current_session: Session) -> set: """get_aws_enabled_regions returns a set of enabled AWS regions""" try: # EC2 Client to check enabled regions service = "ec2" default_region = self.get_default_region(service) ec2_client = current_session.client(service, region_name=default_region) enabled_regions = set() # With AllRegions=False we only get the enabled regions for the account for region in ec2_client.describe_regions(AllRegions=False).get("Regions", []): enabled_regions.add(region.get("RegionName")) return enabled_regions except Exception as error: logger.error(f"{error.__class__.__name__}: {error}") return set() ``` The function returns a JSON file containing the list of regions for the provider. It is used to retrieve the provider’s regions and to validate the region specified by the user. ```json theme={null} # File: prowler/providers/aws/aws_regions_by_service.json (extract) { "services": { "ec2": { "regions": { "aws": [ "af-south-1", "ap-east-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-north-1", "eu-south-1", "eu-west-1", "eu-west-2", "eu-west-3", "me-south-1", "sa-east-1", "us-east-1", "us-east-2", "us-west-1", "us-west-2" ], "aws-cn": ["cn-north-1", "cn-northwest-1"], "aws-eusc": ["eusc-de-east-1"], "aws-us-gov": ["us-gov-east-1", "us-gov-west-1"] } } } } ``` ### Regional Service Implementation For detailed guidance on implementing services for regional services, including code examples, service architecture, and check execution patterns, see the [Regional Service Implementation](./services#regional-service-implementation) section in the Services documentation. **Key concepts covered:** * Threading and parallel processing across regions * Service implementation patterns for regional providers * Cross-region resource attribution and ARN handling * Best practices for performance and error isolation ## Step 1: Create the Provider Backend (CLI Integration) Once the type of provider and its regional architecture are determined, the next step is to start creating the code of the provider. ### SDK Providers General aspects to consider when implementing a new SDK provider: **Definition:** * Use the official SDK of the provider to interact with its resources and APIs. * Examples: AWS (boto3), Azure (azure-identity), GCP (google-auth), Kubernetes (kubernetes), M365 (msal/msgraph), GitHub (PyGithub). **Typical Use Cases:** * Cloud platforms and services with mature Python SDKs. * Need to support multiple authentication methods (profiles, service principals, etc). * Providers that offer comprehensive Python libraries for resource management. **Key Characteristics:** * Authentication and session management handled by the SDK. * Arguments: Depends on the provider, but for example we can have `profile`, `region`, `tenant_id`, `client_id`, `client_secret`, etc. * Outputs: Standardized via SDK models and responses. * Session objects that can be reused across multiple API calls. * Built-in retry logic and error handling. **Implementation Details:** * SDK providers typically use credential objects or session objects provided by the official SDK. * They often support multiple authentication methods (several types of credentials, configuration files, IAM roles, etc.). * Session management includes token refresh, connection pooling, and retry mechanisms. * Resource discovery and enumeration is usually straightforward through SDK methods. *** ### Implementation Guide for SDK Providers Now it's time to start creating the code needed to implement the provider. #### Step 1: Create the Provider Structure **Explanation:** SDK providers require a specific folder structure to organize authentication, configuration, and service management. This structure follows Prowler's conventions and ensures proper integration with the CLI and API. **Required Structure:** ``` prowler/providers// ├── __init__.py ├── _provider.py ├── models.py ├── exceptions/ │ ├── __init__.py │ └── exceptions.py ├── services/ │ ├── service_name1/ │ └── service_name2/ └── lib/ ├── __init__.py ├── arguments/ │ ├── __init__.py │ └── arguments.py ├── mutelist/ │ ├── __init__.py │ └── mutelist.py ├── regions/ │ ├── __init__.py │ └── _regions.py └── service/ ├── __init__.py └── service.py ``` **Key Components:** * **`_provider.py`**: Main provider class with authentication and session management * **`models.py`**: Data structures for identity, session, and provider-specific information * **`exceptions/`**: Custom exception classes for error handling * **`services/`**: Folder that contains all the provider services, how to make a new service is explained in another section. * **`lib/arguments/`**: CLI argument validation and parsing * **`lib/mutelist/`**: Resource exclusion and muting functionality * **`lib/regions/`**: Region management and validation. If the provider is NOT regional, this folder will not be created. * **`lib/service/`**: Base service class for provider-specific services #### Step 2: Implement the Provider Class **Explanation:** The provider class is the core component that handles authentication, session management, and identity information. It inherits from Prowler's base Provider class and implements SDK-specific authentication flows. All providers must share, as far as possible, common patterns for session setup, identity management, and credential validation. Nevertheless, you may encounter changes and must adapt the implementation logic accordingly. A basic example of a common provider implementation is the following: **File:** `prowler/providers//_provider.py` ```python theme={null} import os from typing import Optional, Union from prowler.providers.common.provider import Provider from prowler.providers.common.models import Audit_Metadata, Connection from prowler.config.config import load_and_validate_config_file, get_default_mute_file_path from prowler.lib.logger import logger from prowler.lib.utils.utils import print_boxes # Import your SDK and all the needed libraries for the provider. import your_sdk_library from your_sdk_library.auth_methods import ClientSecretCredential, ProfileCredential, DefaultCredential # Import the needed exceptions, mutelist and models for the provider. from prowler.providers..exceptions.exceptions import Exceptions from prowler.providers..mutelist.mutelist import Mutelist from prowler.providers..models import NeededModels class YourProvider(Provider): """ YourProvider class is the main class for the Your Provider. This class is responsible for initializing the provider, setting up the session, validating credentials, and managing identity information. Attributes: _type (str): The provider type. _session (YourSDKSession): The provider session. _identity (YourProviderIdentityInfo): The provider identity information. _audit_config (dict): The audit configuration. _mutelist (YourProviderMutelist): The provider mutelist. audit_metadata (Audit_Metadata): The audit metadata. """ _type: str = "your_provider" _session: your_sdk_library.Session _identity: YourProviderIdentityInfo _audit_config: dict _mutelist: YourProviderMutelist audit_metadata: Audit_Metadata def __init__( self, # Authentication parameters client_id: str = None, client_secret: str = None, tenant_id: str = None, # Configuration config_path: str = None, config_content: dict = None, mutelist_path: str = None, mutelist_content: dict = None, # Additional provider-specific parameters region: str = None, profile: str = None, ): """ Initializes the YourProvider instance. Args: client_id: The client ID for authentication client_secret: The client secret for authentication tenant_id: The tenant ID for authentication config_path: Path to the configuration file config_content: Configuration content as dictionary mutelist_path: Path to the mutelist file mutelist_content: Mutelist content as dictionary region: The region to use profile: The profile to use Raises: YourProviderSetUpSessionError: If session setup fails YourProviderInvalidCredentialsError: If credentials are invalid """ logger.info("Initializing YourProvider ...") # Setup session using SDK self._session = self.setup_session( client_id, client_secret, tenant_id, region, profile ) # Get identity information self._identity = self.setup_identity(self._session) # Load configuration if config_content: self._audit_config = config_content else: if not config_path: config_path = default_config_file_path self._audit_config = load_and_validate_config_file(self._type, config_path) # Setup mutelist if mutelist_content: self._mutelist = YourProviderMutelist(mutelist_content=mutelist_content) else: if not mutelist_path: mutelist_path = get_default_mute_file_path(self._type) self._mutelist = YourProviderMutelist(mutelist_path=mutelist_path) Provider.set_global_provider(self) @staticmethod def setup_session( client_id: str = None, client_secret: str = None, tenant_id: str = None, region: str = None, profile: str = None, ) -> your_sdk_library.Session: """ Sets up the provider session using the provided credentials. This method handles the authentication flow and creates a session object that can be used to interact with the provider's services. Args: client_id: The client ID for authentication client_secret: The client secret for authentication tenant_id: The tenant ID for authentication region: The region to use profile: The profile to use Returns: YourSDKSession: The authenticated session object Raises: YourProviderSetUpSessionError: If session setup fails """ try: logger.debug("Creating session ...") # Determine authentication method based on provided parameters if client_id and client_secret and tenant_id: # Use client credentials authentication credentials = your_sdk_library.ClientSecretCredential( tenant_id=tenant_id, client_id=client_id, client_secret=client_secret ) auth_method = "Client Credentials" elif profile: # Use profile-based authentication credentials = your_sdk_library.ProfileCredential(profile=profile) auth_method = "Profile" else: # Use default authentication (environment variables, etc.) credentials = your_sdk_library.DefaultCredential() auth_method = "Default" # Create session with credentials session = your_sdk_library.Session( credentials=credentials, region=region ) logger.debug(f"Session created using {auth_method} authentication") return session except Exception as error: logger.critical(f"Failed to setup session: {error}") raise YourProviderSetUpSessionError( original_exception=error, file=os.path.basename(__file__), ) def setup_identity(self, session: your_sdk_library.Session) -> YourProviderIdentityInfo: """ Gets identity information from the provider session. This method retrieves account information, user details, and other identity-related data from the provider. Args: session: The authenticated session object Returns: YourProviderIdentityInfo: The identity information Raises: YourProviderSetUpIdentityError: If identity setup fails """ try: # Use SDK to get account/identity information identity_info = session.get_identity() return YourProviderIdentityInfo( account_id=identity_info.account_id, account_name=identity_info.account_name, region=identity_info.region, user_id=identity_info.user_id, # Add other identity fields as needed ) except Exception as e: logger.error(f"Failed to get identity information: {e}") raise YourProviderSetUpIdentityError( original_exception=e, file=os.path.basename(__file__), ) @property def identity(self): """Returns the provider identity information.""" return self._identity @property def session(self): """Returns the provider session object.""" return self._session @property def type(self): """Returns the provider type.""" return self._type @property def audit_config(self): """Returns the audit configuration.""" return self._audit_config @property def mutelist(self): """Returns the provider mutelist.""" return self._mutelist def print_credentials(self): """ Display account information with color formatting. This method prints the provider credentials and account information in a formatted way using colorama for better readability. """ from colorama import Fore, Style from prowler.lib.utils.utils import print_boxes report_lines = [ f" Account ID: {Fore.YELLOW}{self._identity.account_id}{Style.RESET_ALL}", f" Account Name: {Fore.YELLOW}{self._identity.account_name}{Style.RESET_ALL}", f" Region: {Fore.YELLOW}{self._identity.region}{Style.RESET_ALL}", f" User ID: {Fore.YELLOW}{self._identity.user_id}{Style.RESET_ALL}", ] report_title = f"{Style.BRIGHT}Using the {self._type.upper()} credentials below:{Style.RESET_ALL}" print_boxes(report_lines, report_title) @staticmethod def test_connection( client_id: str = None, client_secret: str = None, tenant_id: str = None, region: str = None, profile: str = None, raise_on_exception: bool = True, provider_id: str = None, ) -> Connection: """ Test connection to the provider. This method validates the provided credentials and tests the connection to the provider's services. Args: client_id: The client ID for authentication client_secret: The client secret for authentication tenant_id: The tenant ID for authentication region: The region to test profile: The profile to use raise_on_exception: Whether to raise exceptions or return Connection object provider_id: The provider ID to validate against Returns: Connection: Connection test result Raises: YourProviderSetUpSessionError: If session setup fails YourProviderInvalidCredentialsError: If credentials are invalid """ try: # Create temporary session for testing test_session = YourProvider.setup_session( client_id, client_secret, tenant_id, region, profile ) # Test the connection by getting identity identity = YourProvider.setup_identity(test_session) # Validate provider ID if provided if provider_id and identity.account_id != provider_id: raise YourProviderInvalidProviderIdError( file=os.path.basename(__file__), ) return Connection( status=True, message=f"Successfully connected to {provider_id or 'provider'}", error=None, ) except Exception as e: if raise_on_exception: raise e return Connection( status=False, message="Failed to connect", error=str(e), ) def get_regions(self) -> set: """ Get available regions for the provider. Returns: set: Set of available region names """ # Implementation depends on your provider # Example for cloud providers that support regions return {"region1", "region2", "region3"} def get_services(self) -> list: """ Get available services for the provider. Returns: list: List of available service names """ # Implementation depends on your provider return ["service1", "service2", "service3"] ``` #### Step 3: Create Models **Explanation:** Models define the data structures used by your provider. They include identity information, session details, and provider-specific configurations. These models ensure type safety and consistent data handling across the provider. **File:** `prowler/providers//models.py` ```python theme={null} # Import the needed generic libraries for the provider. from pydantic import BaseModel from dataclasses import dataclass from typing import Optional, List # Import the needed Prowler libraries for the provider. from prowler.providers.common.models import ProviderOutputOptions from prowler.config.config import output_file_timestamp class YourProviderIdentityInfo: """ Identity information for the provider. This class holds all the identity-related information retrieved from the provider, including account details and user information. """ account_id: str account_name: str region: str user_id: str # Add other identity fields as needed class YourProviderSession: """ Session object that contains the credentials and authentication details for the provider. This class holds the actual credentials and authentication information needed to establish a connection with the provider's services. """ # Authentication credentials access_key: str secret_key: str # Or for other providers: # client_id: str # client_secret: str # tenant_id: str # Connection details region: str ``` #### Step 4: Implement Arguments **Explanation:** Argument validation ensures that the provider receives valid configuration parameters. This step is crucial for preventing runtime errors and providing clear error messages to users. The validation should check for required parameters and validate their format. **File:** `prowler/providers//lib/arguments/arguments.py` ```python theme={null} def init_parser(self): """Init the Provider CLI parser""" _parser = self.subparsers.add_parser( "", parents=[self.common_providers_parser], help=" Provider" ) # Authentication Modes _auth_subparser = _parser.add_argument_group("Authentication Modes") _auth_modes_group = _auth_subparser.add_mutually_exclusive_group() _auth_modes_group.add_argument( "--credentials-file", nargs="?", metavar="FILE_PATH", help="Authenticate using a Service Account Application Credentials JSON file", ) _auth_modes_group.add_argument( "--impersonate-service-account", nargs="?", metavar="SERVICE_ACCOUNT", help="Impersonate a Service Account", ) _parser.add_argument( "--your-provider-region", help="Your Provider Region", type=str, ) _parser.add_argument( "--env-auth", action="store_true", help="Use User and Password environment variables authentication to log in against ", ) # More arguments for the provider. ``` ##### Sensitive CLI Arguments CLI flags that accept secrets (tokens, passwords, API keys) require special handling to protect credentials from leaking in HTML output and process listings: 1. **Use `nargs="?"` with `default=None`** so the flag works both with and without an inline value. This allows the provider to fall back to an environment variable when no value is passed. 2. **Add a `SENSITIVE_ARGUMENTS` frozenset** at the top of the `arguments.py` file listing every flag that accepts secret values: ```python theme={null} SENSITIVE_ARGUMENTS = frozenset({"--your-provider-password", "--your-provider-token"}) ``` Prowler automatically discovers these frozensets and uses them to redact values in HTML output and warn users who pass secrets directly on the command line. 3. **Document the environment variable** in the `help` text so users know the recommended alternative: ```python theme={null} _parser.add_argument( "--your-provider-password", nargs="?", default=None, metavar="PASSWORD", help="Password for authentication. We recommend using the YOUR_PROVIDER_PASSWORD environment variable instead.", ) ``` > [!WARNING] > > Do not add new arguments that require passing secrets as CLI values without an environment variable fallback. Prowler CLI warns users when sensitive flags receive explicit values on the command line. #### Step 5: Implement Mutelist **Explanation:** The mutelist functionality allows users to exclude specific resources or checks from the audit. This is useful for handling false positives or excluding resources that are intentionally configured differently. **File:** `prowler/providers//lib/mutelist/mutelist.py` ```python theme={null} from prowler.lib.mutelist.mutelist import Mutelist from prowler.lib.check.models import CheckReportYourProvider class YourProviderMutelist(Mutelist): """ Mutelist implementation for YourProvider. This class handles the muting functionality for the provider, allowing users to exclude specific checks or resources from audits. """ def is_finding_muted(self, finding: CheckReportYourProvider) -> bool: """ Check if a specific finding is muted. Args: finding: The finding to check """ return self.is_muted(finding.check_id, finding.resource_id) ``` #### Step 6: Implement Regions **Explanation:** Region management is essential for cloud providers that operate across multiple geographic locations. This component handles region validation and provides region-specific functionality. > [!NOTE] > > Regions are optional, only if the provider has regions, for example GitHub does not have regions, but AWS does. **File:** `prowler/providers//lib/regions/_regions.py` ```python theme={null} from typing import List, Set def get_regions() -> List[str]: """ Get list of available regions for the provider. Returns: List[str]: List of available region names """ return [ "region1", "region2", "region3", # ... other regions ] def validate_region(region: str) -> bool: """ Validate if a region is supported. Args: region: The region to validate Returns: bool: True if the region is valid, False otherwise """ return region in get_regions() def get_default_region() -> str: """ Get the default region for the provider. Returns: str: The default region name """ return "region1" def get_global_region() -> str: """ Get the global region for the provider. Returns: str: The global region name """ return "global" ``` #### Step 7: Create Custom Exceptions **Explanation:** Custom exceptions are needed to be able to handle the errors in a more specific way. Prowler uses a structured exception system with error codes, messages, and remediation steps. **File:** `prowler/providers//exceptions.py` ```python theme={null} from prowler.exceptions.exceptions import ProwlerException # Exceptions codes from 7000 to 7999 are reserved for YourProvider exceptions (Numbers as example) class YourProviderBaseException(ProwlerException): """Base class for YourProvider Errors.""" YOUR_PROVIDER_ERROR_CODES = { (7001, "YourProviderCredentialsError"): { "message": "Error loading credentials for YourProvider", "remediation": "Check the credentials and ensure they are properly set up. API_KEY and API_SECRET are required.", }, (7002, "YourProviderAuthenticationError"): { "message": "Authentication failed with YourProvider", "remediation": "Check the API credentials and ensure they are valid and have proper permissions.", }, (7003, "YourProviderInvalidRegionError"): { "message": "Invalid region provided for YourProvider", "remediation": "Check the region and ensure it is a valid region for YourProvider.", }, (7004, "YourProviderSetUpSessionError"): { "message": "Error setting up session", "remediation": "Check the session setup and ensure it is properly configured.", }, (7005, "YourProviderInvalidProviderIdError"): { "message": "Provider does not match with the expected account_id", "remediation": "Check the provider and ensure it matches the expected account_id.", }, } def __init__(self, code, file=None, original_exception=None, message=None): provider = "YourProvider" error_info = self.YOUR_PROVIDER_ERROR_CODES.get((code, self.__class__.__name__)) if message: error_info["message"] = message super().__init__( code=code, source=provider, file=file, original_exception=original_exception, error_info=error_info, ) class YourProviderCredentialsError(YourProviderBaseException): """Base class for YourProvider credentials errors.""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( 7001, file=file, original_exception=original_exception, message=message ) class YourProviderAuthenticationError(YourProviderCredentialsError): def __init__(self, file=None, original_exception=None, message=None): super().__init__( 7002, file=file, original_exception=original_exception, message=message ) class YourProviderInvalidRegionError(YourProviderBaseException): def __init__(self, file=None, original_exception=None, message=None): super().__init__( 7003, file=file, original_exception=original_exception, message=message ) class YourProviderSetUpSessionError(YourProviderCredentialsError): def __init__(self, file=None, original_exception=None, message=None): super().__init__( 7004, file=file, original_exception=original_exception, message=message ) class YourProviderInvalidProviderIdError(YourProviderBaseException): def __init__(self, file=None, original_exception=None, message=None): super().__init__( 7005, file=file, original_exception=original_exception, message=message ) ``` #### Step 8: Implement Service Base Class **Explanation:** The service base class defines a common interface for all services in your provider, since they will inherit from it. It defines the client to make requests to, the audit configuration and the fixer configuration. **File:** `prowler/providers//lib/service/service.py` ```python theme={null} from prowler.providers.._provider import Provider class YourProviderService(BaseService): """ Base service class for YourProvider services. This class provides common functionality for all services within the provider, including session management and error handling. """ def __init__(self, provider: Provider): """ Initialize the service. Args: provider: The provider instance """ self.client = provider.session.get_client(self.service_name) self.audit_config = provider.audit_config self.fixer_config = provider.fixer_config ``` #### Step 9: Register in CLI **Explanation:** Add your provider to the available providers in the CLI. **File:** `prowler/lib/cli/parser.py` ```python theme={null} class ProwlerArgumentParser: # Set the default parser def __init__(self): # CLI Arguments self.parser = argparse.ArgumentParser( prog="prowler", formatter_class=RawTextHelpFormatter, usage="prowler [-h] [--version] {aws,azure,gcp,kubernetes,m365,github,nhn,dashboard,iac,your_provider} ...", epilog=""" Available Providers: {aws,azure,gcp,kubernetes,m365,github,iac,nhn,your_provider} aws AWS Provider azure Azure Provider gcp GCP Provider kubernetes Kubernetes Provider m365 Microsoft 365 Provider github GitHub Provider iac IaC Provider (Preview) nhn NHN Provider (Unofficial) your_provider Your Provider Available components: dashboard Local dashboard To see the different available options on a specific component, run: prowler {provider|dashboard} -h|--help Detailed documentation at https://docs.prowler.com """, ``` #### Step 10: Register in Main **Explanation:** Main registration makes your provider discoverable by Prowler's core system. It's needed to add your provider to the output options and to the compliance evaluation. **File:** `prowler/__main__.py` ```python theme={null} # In the prowler setup output options section if provider == "aws": output_options = AWSOutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "azure": output_options = AzureOutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "gcp": output_options = GCPOutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "kubernetes": output_options = KubernetesOutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "github": output_options = GithubOutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "m365": output_options = M365OutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "nhn": output_options = NHNOutputOptions( args, bulk_checks_metadata, global_provider.identity ) elif provider == "iac": output_options = IACOutputOptions( args, bulk_checks_metadata ) elif provider == "your_provider": output_options = YourProviderOutputOptions( args, bulk_checks_metadata, global_provider.identity ) # Setup Compliance Options elif provider == "your_provider": for compliance_name in input_compliance_frameworks: if compliance_name.startswith("cis_"): # Generate CIS Finding Object (example of compliance with CIS framework) filename = ( f"{output_options.output_directory}/compliance/" f"{output_options.output_filename}_{compliance_name}.csv" ) cis = YourProviderCIS( findings=finding_outputs, compliance=bulk_compliance_frameworks[compliance_name], file_path=filename, ) generated_outputs["compliance"].append(cis) cis.batch_write_data_to_file() ``` #### Step 11: Register in the List of Providers **Explanation:** This is needed to be able to use the provider in the generic checks. The provider must be registered in the `init_global_provider` method to handle CLI arguments and initialization. **File:** `prowler/providers/common/provider.py` ```python theme={null} elif "your_provider" in provider_class_name.lower(): provider_class( username=arguments.your_provider_username, password=arguments.your_provider_password, tenant_id=arguments.your_provider_tenant_id, config_path=arguments.config_file, mutelist_path=arguments.mutelist_file, fixer_config=fixer_config, ) ``` #### Step 12: Add to Config **Explanation:** Configuration registration ensures your provider is recognized by Prowler's configuration system. This enables proper handling of provider-specific settings and defaults. **File:** `prowler/config/config.py` ```python theme={null} class Provider(str, Enum): AWS = "aws" AZURE = "azure" GCP = "gcp" KUBERNETES = "kubernetes" M365 = "m365" GITHUB = "github" YOUR_PROVIDER = "your_provider" # Add your provider here ``` In some cases, you may need to create a new configuration file for your provider, for example, the AWS one that is inside `prowler/providers/aws/config.py`. #### Step 13: Create Compliance Files **Explanation:** Compliance files define the security checks and standards that your provider supports. These JSON files map security controls to specific checks and provide remediation guidance. It's needed to create the folder with an init file to ensure the provider will work, however, adding different compliance files is optional. **Folder:** `prowler/compliance//` ```json theme={null} { "Framework": "CIS", "Version": "1.0", "Provider": "your_provider", "Description": "Description of the compliance framework", # The requirements depends on the framework, for example, CIS has a requirements section with the checks and attributes. "Requirements": [ { "Id": "1.1.1", "Description": "Description of the requirement", "Checks": ["your_provider_check_1", "your_provider_check_2"], "Attributes": [] } ] } ``` #### Step 14: Add Output Support **Explanation:** Output support ensures that your provider's results are properly formatted in Prowler's various output formats (CSV, JSON, HTML, etc.). This step integrates your provider with Prowler's reporting system. **File:** `prowler/lib/outputs/summary_table.py` ```python theme={null} # Add your provider case in the display_summary_table function elif provider.type == "your_provider": entity_type = "Your Entity Type" audited_entities = provider.identity.your_entity_field ``` **File:** `prowler/lib/outputs/finding.py` ```python theme={null} # Add your provider case in the fill_common_finding_data function elif provider.type == "your_provider": output_data["auth_method"] = f"Your Auth Method: {get_nested_attribute(provider, 'identity.auth_type')}" output_data["account_uid"] = get_nested_attribute(provider, "identity.account_id") output_data["account_name"] = get_nested_attribute(provider, "identity.account_name") output_data["resource_name"] = check_output.resource_name output_data["resource_uid"] = check_output.resource_id output_data["region"] = check_output.location # or your location field ``` **File:** `prowler/lib/outputs/outputs.py` ```python theme={null} # Add your provider case in the stdout_report function if finding.check_metadata.Provider == "your_provider": details = finding.your_location_field # e.g., finding.location, finding.namespace, etc. ``` #### Step 15: Generate the HTML Report **Explanation:** The HTML file is needed to be able to generate the HTML report. This step involves adding support for your provider in the HTML output generation system to ensure proper display of assessment summaries and findings. **File:** `prowler/lib/outputs/html/html.py` ```python theme={null} @staticmethod def get_your_provider_assessment_summary(provider: Provider) -> str: """ get_your_provider_assessment_summary gets the HTML assessment summary for your provider Args: provider (Provider): the provider object Returns: str: the HTML assessment summary """ try: return f"""
Your Provider Assessment Summary
  • Your Entity Type: {provider.identity.your_entity_field}
  • Your Location Field: {provider.identity.your_location_field}
Your Provider Credentials
  • Authentication Method: {provider.auth_method}
  • Identity ID: {provider.identity.identity_id}
""" except Exception as error: logger.error( f"{error.__class__.__name__}[{error.__traceback__.tb_lineno}] -- {error}" ) return "" ``` #### Step 16: Add the Check Report Model **Explanation:** Add the provider to the generic models, this is needed to be able to use the provider in the generic checks. **File:** `prowler/providers/check/models.py` ```python theme={null} @dataclass class CheckReportYourProvider(CheckReport): """ Check report for YourProvider. """ resource_name: str resource_id: str def _init_(self, metadata: Dict, resource: Any) -> None: super()._init_(metadata, resource) self.resource_name = resource.name self.resource_id = resource.id ``` #### Step 17: Add Dependencies **Explanation:** Dependencies ensure that your provider's required libraries are available when Prowler is installed. This step adds the necessary SDK or API client to Prowler's dependency management. **File:** `pyproject.toml` ```toml theme={null} [project] requires-python = ">=3.10,<3.13" dependencies = [ # ... other dependencies "your-sdk-library>=1.0.0,<2.0.0", # Add your SDK dependency ] ``` #### Step 18: Create Tests **Explanation:** Testing ensures that your provider works correctly and maintains compatibility as Prowler evolves. Comprehensive tests cover authentication, session management, and provider-specific functionality. **Folder:** `tests/providers//` ```python theme={null} import pytest from prowler.providers.your_provider.your_provider import YourProvider class TestYourProvider: """Test cases for YourProvider.""" def test_provider_initialization_with_client_credentials(self): """Test provider initialization with client credentials.""" provider = YourProvider( client_id="test_client_id", client_secret="test_client_secret", tenant_id="test_tenant_id" ) assert provider.type == "your_provider" assert provider.identity is not None assert provider.session is not None def test_provider_initialization_with_profile(self): """Test provider initialization with profile.""" provider = YourProvider( profile="test_profile" ) assert provider.type == "your_provider" assert provider.identity is not None def test_connection_test(self): """Test connection functionality.""" result = YourProvider.test_connection( client_id="test_client_id", client_secret="test_client_secret", tenant_id="test_tenant_id" ) # Add assertions based on expected behavior def test_identity_retrieval(self): """Test identity information retrieval.""" provider = YourProvider( client_id="test_client_id", client_secret="test_client_secret", tenant_id="test_tenant_id" ) assert provider.identity.account_id is not None assert provider.identity.account_name is not None def test_argument_validation(self): """Test argument validation.""" from prowler.providers.your_provider.lib.arguments.arguments import ( validate_your_provider_arguments ) # Valid arguments validate_your_provider_arguments( client_id="test_client_id", client_secret="test_client_secret", tenant_id="test_tenant_id" ) # Invalid arguments with pytest.raises(ValueError, match="at least one authentication method"): validate_your_provider_arguments() ``` #### Step 19: Update Documentation **Explanation:** Documentation updates ensure that users can find information about your provider in Prowler's documentation. This includes examples, configuration guides, and troubleshooting information. Update the provider documentation to include your new provider in the examples and implementation guidance. *** ### API Providers **Definition:** * Interact directly with the provider's REST API using HTTP requests (e.g., via `requests`). * Examples: NHN Cloud. **Typical Use Cases:** * Providers without an official Python SDK. * Providers with a non-official Python SDK that is not updated and maintained. * Providers that expose REST APIs and meet above requirements. **Key Characteristics:** * Manual management of authentication (tokens, username/password, etc). * Arguments: Depends on the provider, for example, `username`, `password`, `tenant_id`, etc. * Outputs: Dicts or custom models based on API responses. * Custom HTTP session management with headers and authentication. * Manual handling of pagination, rate limiting, and error responses. **Implementation Details:** * API providers require manual HTTP request management using libraries like `requests`. * Authentication typically involves obtaining tokens via login endpoints or OAuth flows. * Session management includes setting appropriate headers (Authorization, Content-Type, etc.). * Resource discovery often requires multiple API calls to different endpoints. * Error handling and retry logic must be implemented manually. *** ### Implementation Guide for API Providers #### Step 1: Create the Provider Structure **Explanation:** API providers require the same structure as the SDK providers, the main difference would be that due to the lack of an official Python SDK, some methods could be implemented differently or not implemented at all. **Required Structure:** ``` prowler/providers// ├── __init__.py ├── _provider.py ├── models.py ├── exceptions/ │ ├── __init__.py │ └── exceptions.py ├── services/ │ ├── service_name1/ │ └── service_name2/ └── lib/ ├── __init__.py ├── arguments/ │ ├── __init__.py │ └── arguments.py ├── mutelist/ │ ├── __init__.py │ └── mutelist.py ├── regions/ │ ├── __init__.py │ └── regions.py └── service/ ├── __init__.py └── service.py ``` **Key Components:** * **`_provider.py`**: Main provider class with HTTP session management * **`models.py`**: Data structures for identity and API responses * **`exceptions/`**: Custom exception classes for API errors * **`services/`**: Folder that contains all the provider services * **`lib/arguments/`**: CLI argument validation and parsing * **`lib/mutelist/`**: Resource exclusion and muting functionality * **`lib/regions/`**: Region management and validation. If the provider is NOT regional, this folder will not be created. * **`lib/service/`**: Base service class for provider-specific services #### Step 2: Implement the Provider Class **Explanation:** The provider class is the core component that handles HTTP session management, authentication, and identity information. It inherits from Prowler's base Provider class and implements API-specific authentication flows using direct HTTP requests. **File:** `prowler/providers//_provider.py` ```python theme={null} import os from typing import Optional import requests from prowler.providers.common.provider import Provider from prowler.providers.common.models import Audit_Metadata, Connection from prowler.config.config import load_and_validate_config_file, get_default_mute_file_path from prowler.lib.logger import logger from prowler.lib.utils.utils import print_boxes # Import the needed exceptions, mutelist and models for the provider. from prowler.providers..exceptions.exceptions import Exceptions from prowler.providers..lib.mutelist.mutelist import Mutelist from prowler.providers..models import NeededModels class APIProvider(Provider): """ APIProvider class is the main class for the API Provider. This class is responsible for initializing the provider, setting up the HTTP session, validating credentials, and managing identity information through direct API calls. Attributes: _type (str): The provider type. _session (requests.Session): The HTTP session for API calls. _identity (APIIdentityInfo): The provider identity information. _audit_config (dict): The audit configuration. _mutelist (APIMutelist): The provider mutelist. audit_metadata (Audit_Metadata): The audit metadata. """ _type: str = "api_provider" _session: Optional[requests.Session] _identity: APIIdentityInfo _audit_config: dict _mutelist: APIMutelist audit_metadata: Audit_Metadata def __init__( self, # Authentication parameters username: str = None, password: str = None, tenant_id: str = None, # Configuration config_path: str = None, config_content: dict = None, mutelist_path: str = None, mutelist_content: dict = None, fixer_config: dict = None, ): """ Initializes the APIProvider instance. Args: username: The API username for authentication password: The API password for authentication tenant_id: The tenant ID for authentication config_path: Path to the configuration file config_content: Configuration content as dictionary mutelist_path: Path to the mutelist file mutelist_content: Mutelist content as dictionary fixer_config: Fixer configuration dictionary Raises: ValueError: If required authentication parameters are missing """ logger.info("Initializing APIProvider ...") # 1) Store argument values with environment variable fallback self._username = username or os.getenv("YOUR_PROVIDER_USERNAME") self._password = password or os.getenv("YOUR_PROVIDER_PASSWORD") self._tenant_id = tenant_id or os.getenv("YOUR_PROVIDER_TENANT_ID") # Validate required parameters if not all([self._username, self._password, self._tenant_id]): raise ValueError("APIProvider requires username, password and tenant_id") # 2) Load audit_config, fixer_config, mutelist self._fixer_config = fixer_config if fixer_config else {} if config_content: self._audit_config = config_content else: if not config_path: config_path = default_config_file_path self._audit_config = load_and_validate_config_file(self._type, config_path) if mutelist_content: self._mutelist = APIMutelist(mutelist_content=mutelist_content) else: if not mutelist_path: mutelist_path = get_default_mute_file_path(self._type) self._mutelist = APIMutelist(mutelist_path=mutelist_path) # 3) Initialize session/token self._token = None self._session = None self.setup_session() # 4) Create identity object self._identity = APIIdentityInfo( tenant_id=self._tenant_id, username=self._username, ) Provider.set_global_provider(self) @property def type(self) -> str: """Returns the type of the provider.""" return self._type @property def identity(self) -> APIIdentityInfo: """Returns the provider identity information.""" return self._identity @property def session(self) -> requests.Session: """Returns the HTTP session for API calls.""" return self._session @property def audit_config(self) -> dict: """Returns the audit configuration.""" return self._audit_config @property def fixer_config(self) -> dict: """Returns the fixer configuration.""" return self._fixer_config @property def mutelist(self) -> APIMutelist: """Returns the provider mutelist.""" return self._mutelist def print_credentials(self) -> None: """ Display account information with color formatting. This method prints the provider credentials and account information in a formatted way using colorama for better readability. """ from colorama import Style report_lines = [ f" Username: {self._username}", f" TenantID: {self._tenant_id}", ] report_title = f"{Style.BRIGHT}Using the {self._type.upper()} credentials below:{Style.RESET_ALL}" print_boxes(report_lines, report_title) def setup_session(self) -> None: """ Implement API authentication method by calling the provider's authentication endpoint. This method performs the authentication flow to obtain an access token and creates a requests.Session with the appropriate headers for API calls. """ # Example for a Keystone-like authentication url = "https://api.your-provider.com/v2.0/tokens" data = { "auth": { "tenantId": self._tenant_id, "passwordCredentials": { "username": self._username, "password": self._password, }, } } try: response = requests.post(url, json=data, timeout=10) if response.status_code == 200: resp_json = response.json() self._token = resp_json["access"]["token"]["id"] # Create session with authentication headers sess = requests.Session() sess.headers.update({ "X-Auth-Token": self._token, "Content-Type": "application/json" }) self._session = sess logger.info("API token acquired successfully and session is set up.") else: logger.critical( f"Failed to get token. Status: {response.status_code}, Body: {response.text}" ) raise ValueError("Failed to get API token") except Exception as e: logger.critical(f"[setup_session] Error: {e}") raise e @staticmethod def test_connection( username: str, password: str, tenant_id: str, raise_on_exception: bool = True, ) -> Connection: """ Test connection to the API provider by performing: 1) Authentication token request 2) (Optional) a small test API call to confirm credentials are valid Args: username: The API username password: The API password tenant_id: The tenant ID raise_on_exception: If True, raise the caught exception; if False, return Connection(error=exception). Returns: Connection: Connection test result """ try: # 1) Validate arguments if not username or not password or not tenant_id: error_msg = "API test_connection error: missing username/password/tenant_id" logger.error(error_msg) raise ValueError(error_msg) # 2) Request authentication token token_url = "https://api.your-provider.com/v2.0/tokens" data = { "auth": { "tenantId": tenant_id, "passwordCredentials": { "username": username, "password": password, }, } } resp = requests.post(token_url, json=data, timeout=10) if resp.status_code != 200: error_msg = f"Failed to get token. Status: {resp.status_code}, Body: {resp.text}" logger.error(error_msg) if raise_on_exception: raise Exception(error_msg) return Connection(error=Exception(error_msg)) # Success token_json = resp.json() api_token = token_json["access"]["token"]["id"] logger.info("API test_connection: Successfully acquired token.") # 3) (Optional) Test API call to confirm credentials are valid test_endpoint = f"https://api.your-provider.com/v2/{tenant_id}/test" headers = { "X-Auth-Token": api_token, "Content-Type": "application/json", } test_resp = requests.get(test_endpoint, headers=headers, timeout=10) if test_resp.status_code == 200: logger.info("API test_connection: Test call success. Credentials valid.") return Connection(is_connected=True) else: error_msg = f"Test call failed. Status: {test_resp.status_code}, Body: {test_resp.text}" logger.error(error_msg) if raise_on_exception: raise Exception(error_msg) return Connection(error=Exception(error_msg)) except Exception as e: logger.critical(f"{e.__class__.__name__}[{e.__traceback__.tb_lineno}]: {e}") if raise_on_exception: raise e return Connection(error=e) @staticmethod def validate_arguments(username: str, password: str, tenant_id: str) -> None: """ Ensures that username, password, and tenant_id are not empty. Args: username: The username to validate password: The password to validate tenant_id: The tenant ID to validate Raises: ValueError: If any required parameter is missing """ if not username or not password or not tenant_id: raise ValueError("API Provider requires username, password and tenant_id.") ``` #### Step 3: Create Models **Explanation:** Models define the data structures used by your API provider. They include identity information and API response structures. These models ensure type safety and consistent data handling across the provider. **File:** `prowler/providers//models.py` This step is common with SDK providers so you can follow the same pattern as [there](#step-3-create-models). #### Step 4: Implement Arguments **Explanation:** Argument validation ensures that the API provider receives valid configuration parameters. This step is crucial for preventing runtime errors and providing clear error messages to users. **File:** `prowler/providers//lib/arguments/arguments.py` Arguments depends on the provider and not the type, so the pattern for this step is the same as the [SDK providers](#step-4-implement-arguments). #### Step 5: Implement Mutelist **Explanation:** The mutelist functionality allows users to exclude specific resources or checks from the audit. This is useful for handling false positives or excluding resources that are intentionally configured differently. **File:** `prowler/providers//lib/mutelist/mutelist.py` The implementation of the mutelist is the same as the [SDK providers](#step-5-implement-mutelist). #### Step 6: Implement Regions **Explanation:** Region management is essential for cloud providers that operate across multiple geographic locations. This component handles region validation and provides region-specific functionality. > [!NOTE] > > Regions are optional, only if the provider has regions, for example GitHub does not have regions, but AWS does. **File:** `prowler/providers//lib/regions/_regions.py` The implementation of the regions is the same as the [SDK providers](#step-6-implement-regions). #### Step 7: Create Custom Exceptions **Explanation:** Custom exceptions provide specific error handling for API-related issues, making debugging and error reporting more effective. Prowler uses a structured exception system with error codes, messages, and remediation steps. **File:** `prowler/providers//exceptions/exceptions.py` ```python theme={null} from prowler.exceptions.exceptions import ProwlerException # Exceptions codes from 8000 to 8999 are reserved for API Provider exceptions (example numbers) class APIProviderBaseException(ProwlerException): """Base class for API Provider Errors.""" APIProvider_ERROR_CODES = { (8000, "APIProviderCredentialsError"): { "message": "API Provider credentials not found or invalid", "remediation": "Check the API Provider API credentials and ensure they are properly set.", }, (8001, "APIProviderAuthenticationError"): { "message": "API Provider authentication failed", "remediation": "Check the API Provider API credentials and ensure they are valid.", }, (8002, "APIProviderSessionError"): { "message": "API Provider session setup failed", "remediation": "Check the session setup and ensure it is properly configured.", }, (8003, "APIProviderIdentityError"): { "message": "API Provider identity setup failed", "remediation": "Check credentials and ensure they are properly set up for API Provider.", }, (8004, "APIProviderAPIError"): { "message": "API Provider API call failed", "remediation": "Check the API request and ensure it is properly formatted.", }, (8005, "APIProviderRateLimitError"): { "message": "API Provider API rate limit exceeded", "remediation": "Reduce the number of API requests or wait before making more requests.", }, } def __init__(self, code, file=None, original_exception=None, message=None): provider = "API Provider" error_info = self.APIProvider_ERROR_CODES.get((code, self.__class__.__name__)) if message: error_info["message"] = message super().__init__( code=code, source=provider, file=file, original_exception=original_exception, error_info=error_info, ) class APIProviderCredentialsError(APIProviderBaseException): """Exception for API Provider credentials errors""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( code=8000, file=file, original_exception=original_exception, message=message, ) class APIProviderAuthenticationError(APIProviderBaseException): """Exception for API Provider authentication errors""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( code=8001, file=file, original_exception=original_exception, message=message, ) class APIProviderSessionError(APIProviderBaseException): """Exception for API Provider session setup errors""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( code=8002, file=file, original_exception=original_exception, message=message, ) class APIProviderIdentityError(APIProviderBaseException): """Exception for API Provider identity setup errors""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( code=8003, file=file, original_exception=original_exception, message=message, ) class APIProviderAPIError(APIProviderBaseException): """Exception for API Provider API errors""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( code=8004, file=file, original_exception=original_exception, message=message, ) class APIProviderRateLimitError(APIProviderBaseException): """Exception for API Provider rate limit errors""" def __init__(self, file=None, original_exception=None, message=None): super().__init__( code=8005, file=file, original_exception=original_exception, message=message, ) ``` #### Step 8: Implement Service Base Class **Explanation:** The service base class defines a common interface for all services in your provider, since they will inherit from it. It defines the client to make requests to, the audit configuration and the fixer configuration. **File:** `prowler/providers//lib/service/service.py` ```python theme={null} from prowler.providers.._provider import Provider class APIProviderService(BaseService): """ Base service class for API Provider services. This class provides common functionality for all services within the provider, including session management and error handling. """ def __init__(self, provider: Provider): """ Initialize the service. Args: provider: The provider instance """ self.client = provider.session.get_client(self.service_name) self.audit_config = provider.audit_config self.fixer_config = provider.fixer_config self.session = provider.session self.base_url = provider.session.base_url self.auth = HTTPDigestAuth( provider.session.public_key, provider.session.private_key, ) self.headers = { "Authorization": self.auth.encode(), "Content-Type": "application/json", } ``` #### Step 9: Register in CLI **Explanation:** Add your provider to the available providers in the CLI. **File:** `prowler/lib/cli/parser.py` This step is the same as the [SDK providers](#step-9-register-in-cli). #### Step 10: Register in Main **Explanation:** Main registration makes your provider discoverable by Prowler's core system. It's needed to add your provider to the output options and to the compliance evaluation. **File:** `prowler/__main__.py` This step is the same as the [SDK providers](#step-10-register-in-main). #### Step 11: Register in the List of Providers **Explanation:** This is needed to be able to use the provider in the generic checks. The provider must be registered in the `init_global_provider` method to handle CLI arguments and initialization. **File:** `prowler/providers/common/provider.py` This step is the same as the [SDK providers](#step-11-register-in-the-list-of-providers). #### Step 12: Add to Config **Explanation:** Configuration registration ensures your API provider is recognized by Prowler's configuration system. This enables proper handling of provider-specific settings and defaults. **File:** `prowler/config/config.py` This step is the same as the [SDK providers](#step-12-add-to-config). #### Step 13: Create Compliance Files **Explanation:** Compliance files define the security checks and standards that your provider supports. These JSON files map security controls to specific checks and provide remediation guidance. It's needed to create the folder with an init file to ensure the provider will work, however, adding different compliance files is optional. **Folder:** `prowler/compliance//` This step is the same as the [SDK providers](#step-13-create-compliance-files). #### Step 14: Add Output Support **Explanation:** Output support ensures that your provider's results are properly formatted in Prowler's various output formats (CSV, JSON, HTML, etc.). This step integrates your provider with Prowler's reporting system. **File:** `prowler/lib/outputs/summary_table.py` This step is the same as the [SDK providers](#step-14-add-output-support). #### Step 15: Generate the HTML Report **Explanation:** The HTML file is needed to be able to generate the HTML report. This step involves adding support for your provider in the HTML output generation system to ensure proper display of assessment summaries and findings. **File:** `prowler/lib/outputs/html/html.py` This step is the same as the [SDK providers](#step-15-generate-the-html-report). #### Step 16: Add the Check Report Model **Explanation:** Add the provider to the generic models, this is needed to be able to use the provider in the generic checks. **File:** `prowler/providers/check/models.py` This step is the same as the [SDK providers](#step-16-add-the-check-report-model). #### Step 17: Create Tests **Explanation:** Testing ensures that your API provider works correctly and maintains compatibility as Prowler evolves. Comprehensive tests cover authentication, session management, and API-specific functionality. **Folder:** `tests/providers//` ```python theme={null} import pytest from prowler.providers.api_provider.api_provider import APIProvider class TestAPIProvider: """Test cases for APIProvider.""" def test_provider_initialization(self): """Test provider initialization with valid credentials.""" provider = APIProvider( username="test_user", password="test_password", tenant_id="test_tenant" ) assert provider.type == "your_api_provider" assert provider.identity is not None assert provider.session is not None def test_connection_test(self): """Test connection functionality.""" result = APIProvider.test_connection( username="test_user", password="test_password", tenant_id="test_tenant" ) # Add assertions based on expected behavior def test_argument_validation(self): """Test argument validation.""" from prowler.providers.api_provider.api_provider import ( APIProvider ) # Valid arguments APIProvider.validate_arguments( username="test_user", password="test_password", tenant_id="test_tenant" ) # Invalid arguments with pytest.raises(ValueError, match="requires username, password and tenant_id"): APIProvider.validate_arguments("", "", "") def test_session_setup(self): """Test session setup.""" provider = APIProvider( username="test_user", password="test_password", tenant_id="test_tenant" ) assert provider.session is not None assert "X-Auth-Token" in provider.session.headers ``` #### Step 18: Update Documentation **Explanation:** Documentation updates ensure that users can find information about your API provider in Prowler's documentation. This includes examples, configuration guides, and troubleshooting information. Update the provider documentation to include your new API provider in the examples and implementation guidance. *** ### Tool/Wrapper Providers **Definition:** * Integrate third-party tools as libraries or subprocesses (e.g., Trivy for IaC). * Examples: IaC (Trivy). **Typical Use Cases:** * Providers that require integration with external security tools. * Tools that need to be executed as subprocesses or imported as libraries. * Providers that require specific tool configurations and argument mapping. * Legacy systems or tools that don't have direct API access. **Key Characteristics:** * No session/identity management required (tool handles this internally). * Arguments: specific to the tool, but for example: `scan_path`, `frameworks`, `exclude_path`, `scan_repository_url`, etc. * Outputs: Tool-specific output formats that need to be parsed and converted. * Tool execution and output parsing. * Configuration file mapping and argument translation. **Implementation Details:** * Tool providers typically execute external tools as subprocesses (e.g., `pwsh` or `trivy` command). * They require mapping between Prowler's interface and the tool's arguments. * Output parsing and conversion to Prowler's standard format is crucial. * Tool-specific configuration files and validation. * Repository cloning and temporary file management for remote scans (if needed). **Note:** This guide provides a general framework for integrating any external tool. The specific implementation details (like repository cloning, authentication tokens, etc.) will depend on your particular tool's requirements. The core pattern is: integrate with Prowler's CLI, execute your tool via subprocess, and parse the output into Prowler's format. *** ### Implementation Guide for Tool/Wrapper Providers #### Step 1: Create the Provider Structure **Explanation:** Tool/Wrapper providers require a specific folder structure to organize tool integration, configuration, and service management. This structure follows Prowler's conventions and ensures proper integration with the CLI and API. **Required Structure:** ``` prowler/providers// ├── __init__.py ├── _provider.py ├── models.py └── lib/ ├── __init__.py └── arguments/ ├── __init__.py └── arguments.py ``` **Key Components:** * **`_provider.py`**: Main provider class with tool integration * **`models.py`**: Data structures for tool output and configuration * **`lib/arguments/`**: CLI argument validation and parsing #### Step 2: Implement the Provider Class **Explanation:** The provider class is the core component that handles tool integration, execution, and output parsing. It inherits from Prowler's base Provider class and implements tool-specific execution flows using subprocesses or library calls. **File:** `prowler/providers//_provider.py` ```python theme={null} import json import subprocess import sys from typing import List from colorama import Fore, Style from prowler.config.config import ( default_config_file_path, load_and_validate_config_file, ) from prowler.lib.check.models import CheckReportYourTool from prowler.lib.logger import logger from prowler.lib.utils.utils import print_boxes from prowler.providers.common.models import Audit_Metadata from prowler.providers.common.provider import Provider class ToolProvider(Provider): """ ToolProvider class is the main class for the Your Tool Provider. This class is responsible for initializing the provider, executing the external tool, parsing tool output, and converting results to Prowler's standard format. Attributes: _type (str): The provider type. _session: Not used for tool providers. _identity (str): Simple identity for tool providers. _audit_config (dict): The audit configuration. audit_metadata (Audit_Metadata): The audit metadata. """ _type: str = "your_tool_provider" audit_metadata: Audit_Metadata def __init__( self, # Tool-specific parameters scan_path: str = ".", tool_specific_arg: str = "default_value", exclude_path: list[str] = [], # Configuration config_path: str = None, config_content: dict = None, fixer_config: dict = {}, # Authentication (if needed for your tool) auth_token: str = None, auth_username: str = None, ): """ Initializes the ToolProvider instance. Args: scan_path: Path to the folder containing files to scan tool_specific_arg: Tool-specific argument for your external tool exclude_path: List of paths to exclude from scan config_path: Path to the configuration file config_content: Configuration content as dictionary fixer_config: Fixer configuration dictionary auth_token: Authentication token for your tool (if needed) auth_username: Username for your tool (if needed) Raises: ValueError: If required parameters are missing """ logger.info("Instantiating YourTool Provider...") # Store tool-specific parameters self.scan_path = scan_path self.tool_specific_arg = tool_specific_arg self.exclude_path = exclude_path self.region = "global" self.audited_account = "local-tool" self._session = None self._identity = "prowler" self._auth_method = "No auth" # Handle tool authentication if needed if auth_token: self.auth_token = auth_token self._auth_method = "Token" logger.info("Using token for tool authentication") elif auth_username: self.auth_username = auth_username self._auth_method = "Username" logger.info("Using username for tool authentication") logger.info("Using username for tool authentication") else: logger.debug("No authentication method provided; proceeding without authentication.") # Audit Config if config_content: self._audit_config = config_content else: if not config_path: config_path = default_config_file_path self._audit_config = load_and_validate_config_file(self._type, config_path) # Fixer Config self._fixer_config = fixer_config # Mutelist (not needed for tool providers since tools have their own mutelist logic) self._mutelist = None Provider.set_global_provider(self) @property def auth_method(self): """Returns the authentication method used.""" return self._auth_method @property def type(self): """Returns the type of the provider.""" return self._type @property def identity(self): """Returns the provider identity.""" return self._identity @property def session(self): """Returns the session (not used for tool providers).""" return self._session @property def audit_config(self): """Returns the audit configuration.""" return self._audit_config @property def fixer_config(self): """Returns the fixer configuration.""" return self._fixer_config def setup_session(self): """Tool providers don't need a session since they use external tools directly""" return None def _process_check(self, finding: dict, check: dict, status: str) -> CheckReportYourTool: """ Process a single check (failed or passed) and create a CheckReportYourTool object. Args: finding: The finding object from tool output check: The individual check data status: The status of the check ("FAIL", "PASS", or "MUTED") Returns: CheckReportYourTool: The processed check report """ try: metadata_dict = { "Provider": "your_tool_provider", "CheckID": check.get("check_id", ""), "CheckTitle": check.get("check_name", ""), "CheckType": ["Your Tool Provider"], "ServiceName": finding["check_type"], "SubServiceName": "", "ResourceIdTemplate": "", "Severity": ( check.get("severity", "low").lower() if check.get("severity") else "low" ), "ResourceType": "your_tool", "Description": check.get("check_name", ""), "Risk": "", "RelatedUrl": ( check.get("guideline", "") if check.get("guideline") else "" ), "Remediation": { "Code": { "NativeIaC": "", "Terraform": "", "CLI": "", "Other": "", }, "Recommendation": { "Text": "", "Url": ( check.get("guideline", "") if check.get("guideline") else "" ), }, }, "Categories": [], "DependsOn": [], "RelatedTo": [], "Notes": "", } # Convert metadata dict to JSON string metadata = json.dumps(metadata_dict) report = CheckReportYourTool(metadata=metadata, finding=check) report.status = status report.resource_tags = check.get("entity_tags", {}) report.status_extended = check.get("check_name", "") if status == "MUTED": report.muted = True return report except Exception as error: logger.critical( f"{error.__class__.__name__}:{error.__traceback__.tb_lineno} -- {error}" ) sys.exit(1) def run(self) -> List[CheckReportYourTool]: """ Main execution method that handles tool execution. Returns: List[CheckReportYourTool]: List of check reports from the tool scan """ return self.run_scan(self.scan_path, self.exclude_path) def run_scan( self, directory: str, exclude_path: list[str] ) -> List[CheckReportYourTool]: """ Execute the external tool and parse its output. Args: directory: Directory to scan frameworks: List of frameworks to scan exclude_path: List of paths to exclude Returns: List[CheckReportYourTool]: List of check reports """ try: logger.info(f"Running YourTool scan on {directory} ...") # Build the tool command tool_command = [ "your_tool_command", # Add your tool-specific arguments here, this are just examples "-d", directory, "-o", "json", "-f", ",".join(frameworks), ] if exclude_path: tool_command.extend(["--skip-path", ",".join(exclude_path)]) # Run the tool with JSON output process = subprocess.run( tool_command, capture_output=True, text=True, ) # Log tool's error output if any if process.stderr: logger.error(process.stderr) try: output = json.loads(process.stdout) if not output: logger.warning("No findings returned from YourTool scan") return [] except Exception as error: logger.critical( f"{error.__class__.__name__}:{error.__traceback__.tb_lineno} -- {error}" ) sys.exit(1) reports = [] # If only one framework has findings, the output is a dict, otherwise it's a list of dicts if isinstance(output, dict): output = [output] # Process all frameworks findings for finding in output: results = finding.get("results", {}) # Process failed checks failed_checks = results.get("failed_checks", []) for failed_check in failed_checks: report = self._process_check(finding, failed_check, "FAIL") reports.append(report) # Process passed checks passed_checks = results.get("passed_checks", []) for passed_check in passed_checks: report = self._process_check(finding, passed_check, "PASS") reports.append(report) # Process skipped checks (muted) skipped_checks = results.get("skipped_checks", []) for skipped_check in skipped_checks: report = self._process_check(finding, skipped_check, "MUTED") reports.append(report) return reports except Exception as error: if "No such file or directory: 'your_tool_command'" in str(error): logger.critical("Please, install your_tool using 'pip install your_tool'") sys.exit(1) logger.critical( f"{error.__class__.__name__}:{error.__traceback__.tb_lineno} -- {error}" ) sys.exit(1) def print_credentials(self): """ Display scan information with color formatting. This method prints the tool scan information in a formatted way using colorama for better readability. """ if self.scan_repository_url: report_title = ( f"{Style.BRIGHT}Scanning remote repository:{Style.RESET_ALL}" ) report_lines = [ f"Repository: {Fore.YELLOW}{self.scan_repository_url}{Style.RESET_ALL}", ] else: report_title = ( f"{Style.BRIGHT}Scanning local directory:{Style.RESET_ALL}" ) report_lines = [ f"Directory: {Fore.YELLOW}{self.scan_path}{Style.RESET_ALL}", ] if self.exclude_path: report_lines.append( f"Excluded paths: {Fore.YELLOW}{', '.join(self.exclude_path)}{Style.RESET_ALL}" ) report_lines.append( f"Frameworks: {Fore.YELLOW}{', '.join(self.frameworks)}{Style.RESET_ALL}" ) report_lines.append( f"Authentication method: {Fore.YELLOW}{self.auth_method}{Style.RESET_ALL}" ) print_boxes(report_lines, report_title) ``` #### Step 3: Create Models **Explanation:** Models define the data structures used by your tool provider. They include output options and tool-specific configurations. These models ensure type safety and consistent data handling across the provider. **File:** `prowler/providers//models.py` ```python theme={null} from prowler.config.config import output_file_timestamp from prowler.providers.common.models import ProviderOutputOptions class YourToolOutputOptions(ProviderOutputOptions): """ YourToolOutputOptions overrides ProviderOutputOptions for tool-specific output logic. For example, generating a filename that includes the tool name. Attributes inherited from ProviderOutputOptions: - output_filename (str): The base filename used for generated reports. - output_directory (str): The directory to store the output files. - ... see ProviderOutputOptions for more details. Methods: - __init__: Customizes the output filename logic for the tool provider. """ def __init__(self, arguments, bulk_checks_metadata): super().__init__(arguments, bulk_checks_metadata) # If --output-filename is not specified, build a default name. if not getattr(arguments, "output_filename", None): self.output_filename = f"prowler-output-your_tool-{output_file_timestamp}" # If --output-filename was explicitly given, respect that else: self.output_filename = arguments.output_filename ``` #### Step 4: Implement Arguments **Explanation:** Argument validation ensures that the tool provider receives valid configuration parameters. This step is crucial for preventing runtime errors and providing clear error messages to users. **File:** `prowler/providers//lib/arguments/arguments.py` ```python theme={null} # Add your tool-specific choices if needed TOOL_SPECIFIC_CHOICES = [ "option1", "option2", "option3", # Add your tool's supported options ] def init_parser(self): """Init the Provider CLI parser""" _parser = self.subparsers.add_parser( "", parents=[self.common_providers_parser], help=" Provider" ) # Scan Path _scan_subparser = _parser.add_argument_group("Scan Path") _scan_subparser.add_argument( "--scan-path", "-P", dest="scan_path", default=".", help="Path to the folder containing your files to scan. Default: current directory.", ) _scan_subparser.add_argument( "--tool-specific-arg", dest="tool_specific_arg", default="default_value", choices=TOOL_SPECIFIC_CHOICES, help="Tool-specific argument for your external tool. Default: default_value", ) _scan_subparser.add_argument( "--exclude-path", dest="exclude_path", nargs="+", default=[], help="Comma-separated list of paths to exclude from the scan. Default: none", ) # Authentication (if needed for your tool) _scan_subparser.add_argument( "--auth-token", dest="auth_token", nargs="?", default=None, help="Authentication token for your tool. If not provided, will use YOUR_TOOL_AUTH_TOKEN env var.", ) _scan_subparser.add_argument( "--auth-username", dest="auth_username", nargs="?", default=None, help="Username for your tool authentication. If not provided, will use YOUR_TOOL_AUTH_USERNAME env var.", ) def validate_arguments(arguments): """ Validate tool-specific arguments. Args: arguments: The parsed arguments Returns: tuple: (is_valid, error_message) """ scan_path = getattr(arguments, "scan_path", None) scan_repository_url = getattr(arguments, "scan_repository_url", None) if scan_path and scan_repository_url: # If scan_path is set to default ("."), allow scan_repository_url if scan_path != ".": return ( False, "--scan-path (-P) and --scan-repository-url (-R) are mutually exclusive. Please specify only one.", ) return (True, "") ``` #### Step 5: Register in CLI **Explanation:** Add your provider to the available providers in the CLI. **File:** `prowler/lib/cli/parser.py` This step is the same as the [SDK providers](#step-9-register-in-cli). #### Step 6: Register in Main **Explanation:** Main registration makes your provider discoverable by Prowler's core system. It's needed to add your provider to the output options and to the compliance evaluation. **File:** `prowler/__main__.py` This step is the same as the [SDK providers](#step-10-register-in-main). #### Step 7: Register in the List of Providers **Explanation:** This is needed to be able to use the provider in the generic checks. The provider must be registered in the `init_global_provider` method to handle CLI arguments and initialization. **File:** `prowler/providers/common/provider.py` This step is the same as the [SDK providers](#step-11-register-in-the-list-of-providers). #### Step 8: Add to Config **Explanation:** Configuration registration ensures your tool provider is recognized by Prowler's configuration system. This enables proper handling of provider-specific settings and defaults. **File:** `prowler/config/config.py` This step is the same as the [SDK providers](#step-12-add-to-config). In some cases, you may need to create a new configuration file for your provider, for example, the AWS one that is inside `prowler/providers/aws/config.py`. #### Step 9: Create Compliance Files **Explanation:** Compliance files define the security checks and standards that your provider supports. These JSON files map security controls to specific checks and provide remediation guidance. It's needed to create the folder with an init file to ensure the provider will work, however, adding different compliance files is optional. **Folder:** `prowler/compliance//` This step is the same as the [SDK providers](#step-13-create-compliance-files). #### Step 10: Add Output Support **Explanation:** Output support ensures that your provider's results are properly formatted in Prowler's various output formats (CSV, JSON, HTML, etc.). This step integrates your provider with Prowler's reporting system. **File:** `prowler/lib/outputs/summary_table.py` This step is the same as the [SDK providers](#step-14-add-output-support). #### Step 11: Generate the HTML Report **Explanation:** The HTML file is needed to be able to generate the HTML report. This step involves adding support for your provider in the HTML output generation system to ensure proper display of assessment summaries and findings. **File:** `prowler/lib/outputs/html/html.py` This step is the same as the [SDK providers](#step-15-generate-the-html-report). #### Step 12: Add the Check Report Model **Explanation:** Add the provider to the generic models, this is needed to be able to use the provider in the generic checks. **File:** `prowler/providers/check/models.py` This step is the same as the [SDK providers](#step-16-add-the-check-report-model). #### Step 13: Create Tests **Explanation:** Testing ensures that your tool provider works correctly and maintains compatibility as Prowler evolves. Comprehensive tests cover tool execution, output parsing, and provider-specific functionality. **Folder:** `tests/providers//` ```python theme={null} import pytest import tempfile import os from prowler.providers.your_tool_provider.your_tool_provider import ToolProvider class TestToolProvider: """Test cases for ToolProvider.""" def test_provider_initialization(self): """Test provider initialization with valid parameters.""" provider = ToolProvider( scan_path=".", frameworks=["framework1"] ) assert provider.type == "your_tool_provider" assert provider.identity == "prowler" assert provider.scan_path == "." def test_tool_execution(self): """Test tool execution and output parsing.""" provider = ToolProvider(scan_path=".") # Mock the subprocess call and test output parsing # This will depend on your specific tool's output format def test_argument_validation(self): """Test argument validation.""" from prowler.providers.your_tool_provider.lib.arguments.arguments import ( validate_arguments ) # Valid arguments class MockArgs: scan_path = "." tool_specific_arg = "value" is_valid, message = validate_arguments(MockArgs()) assert is_valid is True # Add more test cases as needed for your specific tool provider def test_print_credentials(self): """Test print_credentials method.""" provider = ToolProvider( scan_path="/test/path", frameworks=["framework1"] ) # This should not raise any exceptions provider.print_credentials() ``` #### Step 14: Update Documentation **Explanation:** Documentation updates ensure that users can find information about your tool provider in Prowler's documentation. This includes examples, configuration guides, and troubleshooting information. Update the provider documentation to include your new tool provider in the examples and implementation guidance. *** ## Step 2: Integrate the Provider in the API This step is required only if you want your provider to be available in the API and UI. The API integration involves several components: ### 2.1. Backend API Models **Location:** `api/src/backend/api/models.py` Add your provider to the `ProviderChoices` enum and implement UID validation: ```python theme={null} class ProviderChoices(models.TextChoices): AWS = "aws", "AWS" AZURE = "azure", "Azure" GCP = "gcp", "GCP" KUBERNETES = "kubernetes", "Kubernetes" M365 = "m365", "Microsoft 365" GITHUB = "github", "GitHub" NHN = "nhn", "NHN Cloud" IAC = "iac", "Infrastructure as Code" YOUR_PROVIDER = "your_provider", "Your Provider" # Add your provider here @staticmethod def validate_your_provider_uid(value): """Validate your provider UID format.""" if not re.match(r"^your-regex-pattern$", value): raise ModelValidationError( detail="Your provider UID must follow the specified format.", code="your-provider-uid", pointer="/data/attributes/uid", ) ``` **Provider Model:** The `Provider` model already exists and supports all provider types. Ensure your provider type is included in the choices. ### 2.2. Add the Provider to the Provider Choices Update the `return_prowler_provider` function to include your provider. This function is crucial for the API to instantiate the correct provider class. **File:** `api/src/backend/api/utils.py` ```python theme={null} from prowler.providers.your_provider.your_provider import YourProvider # Add your import def return_prowler_provider( provider: Provider, ) -> [ AwsProvider | AzureProvider | GcpProvider | GithubProvider | KubernetesProvider | M365Provider | YourProvider # Add your provider to the return type annotation ]: """Return the Prowler provider class based on the given provider type.""" match provider.provider: case Provider.ProviderChoices.AWS.value: prowler_provider = AwsProvider case Provider.ProviderChoices.AZURE.value: prowler_provider = AzureProvider case Provider.ProviderChoices.GCP.value: prowler_provider = GcpProvider case Provider.ProviderChoices.KUBERNETES.value: prowler_provider = KubernetesProvider case Provider.ProviderChoices.M365.value: prowler_provider = M365Provider case Provider.ProviderChoices.GITHUB.value: prowler_provider = GithubProvider case Provider.ProviderChoices.YOUR_PROVIDER.value: # Add your provider here prowler_provider = YourProvider case _: raise ValueError(f"Provider type {provider.provider} not supported") return prowler_provider ``` **Also update the `initialize_prowler_provider` function:** ```python theme={null} def initialize_prowler_provider( provider: Provider, mutelist_processor: Processor | None = None, ) -> ( AwsProvider | AzureProvider | GcpProvider | GithubProvider | KubernetesProvider | M365Provider | YourProvider # Add your provider to the return type annotation ): """Initialize a Prowler provider instance based on the given provider type.""" prowler_provider = return_prowler_provider(provider) prowler_provider_kwargs = get_prowler_provider_kwargs(provider, mutelist_processor) return prowler_provider(**prowler_provider_kwargs) ``` **Note:** The `match` statement requires Python 3.10+. If you're using an older version, you can use traditional `if-elif` statements instead. ### 2.3. API Serializers Create or update serializers for your provider. You'll need to add your provider to the validation logic: **File:** `api/src/backend/api/v1/serializers.py` ```python theme={null} def validate_secret_based_on_provider(provider_type, secret): """Validate provider-specific secrets.""" if provider_type == Provider.ProviderChoices.AWS.value: serializer = AWSProviderSecret(data=secret) elif provider_type == Provider.ProviderChoices.AZURE.value: serializer = AzureProviderSecret(data=secret) elif provider_type == Provider.ProviderChoices.GCP.value: serializer = GCPProviderSecret(data=secret) elif provider_type == Provider.ProviderChoices.YOUR_PROVIDER.value: # Add your provider here serializer = YourProviderSecret(data=secret) # ... other providers if serializer.is_valid(): return serializer.validated_data else: raise serializers.ValidationError(serializer.errors) class YourProviderSecret(serializers.Serializer): """Serializer for your provider credentials.""" your_auth_field = serializers.CharField(required=True) your_optional_field = serializers.CharField(required=False) class Meta: resource_name = "provider-secrets" ``` Also update the providers included in the serializer: **File:** `api/src/backend/api/v1/serializer_utils/providers.py` ```python theme={null} @extend_schema_field( { "oneOf": [ # ... existing provider schemas ... { "type": "object", "title": "Your Provider Credentials", "properties": { "your_auth_field": { "type": "string", "description": "Your provider authentication field description.", }, "your_optional_field": { "type": "string", "description": "Optional field for your provider (if applicable).", }, "your_required_field": { "type": "string", "description": "Required field for your provider authentication.", } }, "required": ["your_auth_field", "your_required_field"] }, # ... other existing schemas ... ] } ) ``` ### 2.4. Database Migration Create a new migration to add your provider to the database. This is crucial for the API to recognize your provider type. **File:** `api/src/backend/api/migrations/XXXX_your_provider.py` ```python theme={null} # Generated by Django X.X.X on YYYY-MM-DD from django.db import migrations import api.db_utils class Migration(migrations.Migration): dependencies = [ ("api", "previous_migration_name"), # Update this to the latest migration ] operations = [ migrations.AlterField( model_name="provider", name="provider", field=api.db_utils.ProviderEnumField( choices=[ ("aws", "AWS"), ("azure", "Azure"), ("gcp", "GCP"), ("kubernetes", "Kubernetes"), ("m365", "M365"), ("github", "GitHub"), ("your_provider", "Your Provider"), # Add your provider here ], default="aws", ), ), migrations.RunSQL( "ALTER TYPE provider ADD VALUE IF NOT EXISTS 'your_provider';", reverse_sql=migrations.RunSQL.noop, ), ] ``` **Important Notes:** * **Migration Number**: Use the next sequential number (e.g., if latest is 0044, use 0045) * **Dependencies**: Update the `dependencies` list to point to the most recent migration * **Choices Array**: Add your provider to the `choices` array with proper display name * **SQL Operation**: The `RunSQL` operation adds your provider to the PostgreSQL enum type * **Reverse SQL**: Use `migrations.RunSQL.noop` since adding enum values cannot be easily reversed **Migration Naming Convention:** * Format: `XXXX_your_provider.py` (e.g., `0045_your_provider.py`) * Use descriptive names that indicate what the migration does * Follow the existing pattern in the migrations folder ### 2.5. Update the V1 Yaml Update the OpenAPI specification (`v1.yaml`) to include your provider in all relevant endpoints and schemas. This is crucial for API documentation and client generation. **File:** `api/src/backend/api/specs/v1.yaml` #### 2.5.1. Provider Enum Values Add your provider to the provider enum in the Provider schema: ```yaml theme={null} # Around line 12150 in v1.yaml Provider: type: object properties: attributes: properties: provider: enum: - aws - azure - gcp - kubernetes - m365 - github - your_provider # Add your provider here type: string description: |- * `aws` - AWS * `azure` - Azure * `gcp` - GCP * `kubernetes` - Kubernetes * `m365` - M365 * `github` - GitHub * `your_provider` - Your Provider # Add your provider here ``` #### 2.5.2. Provider Credential Schemas Add your provider's credential schema to the integration configuration. This defines how your provider's credentials are structured: ```yaml theme={null} # Around line 11100 in v1.yaml, in the integration configuration - type: object title: Your Provider Credentials # Add your provider here properties: your_auth_field: type: string description: Your provider authentication field description. your_optional_field: type: string description: Optional field for your provider (if applicable). your_required_field: type: string description: Required field for your provider authentication. required: - your_auth_field - your_required_field ``` #### 2.5.3. Example Provider Schemas Here are examples of how existing providers are documented: **AWS Provider:** ```yaml theme={null} - type: object title: AWS Static Credentials properties: aws_access_key_id: type: string description: The AWS access key ID. aws_secret_access_key: type: string description: The AWS secret access key. required: - aws_access_key_id - aws_secret_access_key - type: object title: AWS Assume Role properties: role_arn: type: string description: The Amazon Resource Name (ARN) of the role to assume. external_id: type: string description: An identifier to enhance security for role assumption. required: - role_arn - external_id ``` **GitHub Provider:** ```yaml theme={null} - type: object title: GitHub Personal Access Token properties: personal_access_token: type: string description: GitHub personal access token for authentication. required: - personal_access_token - type: object title: GitHub OAuth App Token properties: oauth_app_token: type: string description: GitHub OAuth App token for authentication. required: - oauth_app_token ``` **M365 Provider:** ```yaml theme={null} - type: object title: M365 Static Credentials properties: client_id: type: string description: The Azure application (client) ID for authentication in Azure AD. client_secret: type: string description: The client secret associated with the application (client) ID. tenant_id: type: string description: The Azure tenant ID, representing the directory where the application is registered. user: type: email description: User microsoft email address. password: type: string description: User password. required: - client_id - client_secret - tenant_id - user - password ``` #### 2.5.4. Important Notes * **Position**: Add your schema in the `oneOf` array alongside existing providers * **Structure**: Follow the exact pattern of other providers (title, properties, required fields) * **Descriptions**: Provide clear, helpful descriptions for each field * **Required Fields**: Specify which fields are mandatory in the `required` array * **Field Types**: Use appropriate JSON schema types (`string`, `integer`, `boolean`, `email`, etc.) * **Validation**: Add any field-specific validation patterns or constraints * **Documentation**: Ensure your provider appears in the generated API documentation ### 2.6. Testing API Integration Create tests for your provider: **Location:** `api/src/backend/api/tests/` ```python theme={null} class YourProviderAPITestCase(APITestCase): def setUp(self): self.user = User.objects.create_user(username='testuser', password='testpass') self.client.force_authenticate(user=self.user) def test_create_your_provider(self): data = { 'provider': 'your_provider', 'uid': 'valid-uid-123', 'alias': 'Test Account' } response = self.client.post('/api/v1/providers/', data) self.assertEqual(response.status_code, 201) self.assertEqual(response.data['provider'], 'your_provider') def test_your_provider_uid_validation(self): """Test UID validation for your provider.""" invalid_uids = [ 'invalid@uid', '-invalid-start', 'a' * 40, # Too long ] for invalid_uid in invalid_uids: data = { 'provider': 'your_provider', 'uid': invalid_uid, 'alias': 'Test' } response = self.client.post('/api/v1/providers/', data) self.assertEqual(response.status_code, 400) self.assertIn('your-provider-uid', str(response.data)) def test_add_your_provider_credentials(self): # Create provider first provider = Provider.objects.create( user=self.user, provider='your_provider', uid='valid-uid-123' ) # Add credentials credentials_data = { 'secret_type': 'your_provider_credentials', 'secret': { 'your_auth_field': 'auth_value', 'your_optional_field': 'optional_value' }, 'provider': provider.id } response = self.client.post('/api/v1/providers/secrets/', credentials_data) self.assertEqual(response.status_code, 201) ``` #### 2.6.1. Add Your Mocked Provider to the Tests If needed, add a named provider fixture or extend the provider factory defaults so tests can request only the provider they need. **File:** `api/src/backend/conftest.py` ```python theme={null} @pytest.fixture def your_provider(provider_factory): return provider_factory( provider="your_provider", uid="your_uid", alias="your_alias", ) ``` ### 2.7. Compliance and Output Support Add your provider to the compliance export functionality: **File:** `api/src/backend/tasks/jobs/export.py` ```python theme={null} COMPLIANCE_FRAMEWORKS = { "aws": [...], "azure": [...], "gcp": [...], "kubernetes": [...], "m365": [...], "github": [...], "your_provider": [ # Add your provider here (lambda name: name.startswith("cis_"), YourProviderCIS), (lambda name: name.startswith("iso27001_"), YourProviderISO27001), ], } ``` If your provider has specific fields, add them to the finding transformation: **File:** `prowler/lib/outputs/finding.py` ```python theme={null} def transform_api_finding(cls, finding, provider, metadata_cache=None) -> "Finding": # ... existing code ... # Your provider specific field if provider.type == "your_provider": finding.your_field = resource.your_field # ... rest of the code ... ``` ### 2.8. API Endpoints Your provider will be available through these endpoints: * `GET /api/v1/providers/` - List all providers * `POST /api/v1/providers/` - Create a new provider * `GET /api/v1/providers/{id}/` - Get provider details * `PUT /api/v1/providers/{id}/` - Update provider * `DELETE /api/v1/providers/{id}/` - Delete provider * `POST /api/v1/providers/secrets/` - Add provider credentials ### 2.9. Update the Provider If Needed Depending on your provider's authentication requirements, you may need to add new authentication methods that are compatible with the API. This involves updating the provider class to support additional credential types beyond the basic ones. #### 2.9.1. Adding New Authentication Methods If your provider requires specific authentication methods, you'll need to: 1. **Update the provider constructor** to accept new authentication parameters 2. **Extend the credential handling** to support the new authentication method 3. **Update the API serializers** to include the new credential fields 4. **Modify the OpenAPI specification** to document the new authentication schema #### 2.9.2. Example: GitHub Provider Authentication Methods The GitHub provider demonstrates how to implement multiple authentication methods: ```python theme={null} # In prowler/providers/github/github_provider.py def __init__( self, # Authentication methods personal_access_token: str = "", oauth_app_token: str = "", github_app_key: str = "", #Needed for the API integration github_app_key_content: str = "", github_app_id: int = 0, # Provider configuration config_path: str = None, # ... other parameters ): """ Initialize GitHub provider. Args: personal_access_token (str): GitHub personal access token. oauth_app_token (str): GitHub OAuth App token. github_app_key (str): GitHub App key. github_app_key_content (str): GitHub App key content. github_app_id (int): GitHub App ID. config_path (str): Path to the audit configuration file. # ... other parameters """ super().__init__( personal_access_token, oauth_app_token, github_app_id, github_app_key, github_app_key_content, ) ``` *** ## Step 3: Integrate the Provider in the UI TBD *** ## Provider Implementation Guidance Use existing providers as templates, this will help you to understand better the structure and the implementation will be easier: * [AWS (SDK)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_provider.py) * [Azure (SDK)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/azure_provider.py) * [GCP (SDK)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/gcp_provider.py) * [Kubernetes (SDK)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/kubernetes_provider.py) * [M365 (SDK/Wrapper)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/m365_provider.py) * [GitHub (SDK)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/github_provider.py) * [NHN (API)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/nhn/nhn_provider.py) * [IAC (Tool)](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/iac/iac_provider.py) * [MongoDB Atlas](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/mongodbatlas/mongodbatlas_provider.py) *** ## Best Practices * **Code Quality & Documentation** * **Comprehensive Docstrings**: Every class, method, and function should have detailed docstrings following Prowler's format ```python theme={null} def method_name(self, param: str) -> str: """ Brief description of what the method does. Args: param: Description of the parameter Returns: Description of the return value Raises: ExceptionType: When and why this exception occurs """ ``` * **Type Hints**: Use type hints for all function parameters and return values ```python theme={null} from typing import Optional, List, Dict, Any ``` * **Logging**: Implement proper logging using Prowler's logger ```python theme={null} from prowler.lib.logger import logger logger.info("Operation completed successfully") logger.warning("Something to be aware of") logger.error("Something went wrong") logger.critical("Critical error that may cause failure") ``` * **Error Handling & Validation** * **Custom Exceptions**: Create provider-specific exceptions for better error handling * **Input Validation**: Validate all inputs and provide clear error messages * **Graceful Degradation**: Handle errors gracefully without crashing the entire scan * **Raise on Exception**: Use `raise_on_exception` parameter for test methods * **Testing & Quality Assurance** * **Comprehensive Test Coverage**: Aim for >80% test coverage * **Test Naming**: Use descriptive test names: `test_method_name_scenario` * **Test Organization**: Group related tests in test classes * **Mock External Dependencies**: Mock external API calls and services * **Test Edge Cases**: Include tests for error conditions and edge cases * **End-to-End Testing**: Test the provider on real infrastructure * **Performance & Security** * **Session Management**: Reuse sessions when possible, don't create new ones unnecessarily * **Rate Limiting**: Implement rate limiting for API calls to avoid hitting limits * **Resource Cleanup**: Ensure proper cleanup of temporary resources * **Authentication Security**: Never log sensitive credentials or tokens * **Code Organization** * **Single Responsibility**: Each method should have one clear purpose * **Consistent Naming**: Follow Prowler's naming conventions * **Modular Design**: Break complex functionality into smaller, testable methods * **Configuration Management**: Use configuration files for provider-specific settings * **Documentation & Maintenance** * **README Updates**: Update provider-specific documentation * **Changelog**: Document changes and new features with a fragment under `prowler/changelog.d/` (see the [Pull Request Template](https://github.com/prowler-cloud/prowler/blob/master/.github/pull_request_template.md)) * **Examples**: Provide usage examples and common scenarios * **Troubleshooting**: Include common issues and solutions * **Documentation**: Update the provider documentation to include your new tool provider in the examples and implementation guidance. * **Integration Standards** * **CLI Consistency**: Follow Prowler's CLI argument patterns * **Output Format**: Ensure outputs are compatible with Prowler's reporting system * **Compliance Mapping**: Map provider checks to relevant compliance frameworks * **Backward Compatibility**: Maintain compatibility when possible * **AI-Assisted Development** * **Use Rules**: Use rules to ensure the code generated by AI is following the way of working in Prowler. *** ## OCSF Field Requirements for Prowler Cloud Integration When implementing a new provider that supports the `--push-to-cloud` feature, specific OCSF fields must be correctly populated to ensure proper findings ingestion into Prowler Cloud. ### Required OCSF Fields The following fields in the OCSF output are critical for successful ingestion: | Field | Requirement | Description | | - | - | - | | `provider_uid` | Must match the UID used when registering the provider in the API | This identifier links findings to the correct provider in Prowler Cloud | | `provider` | Must be the provider name | The name of the provider (e.g., `aws`, `azure`, `gcp`, `googleworkspace`) | | `finding_info.uid` | Must be unique | Each finding must have a unique identifier to avoid duplicates | | `resources.uid` | Must have a value | The resource UID cannot be empty; it identifies the specific resource being assessed | ### Implementation Reference These fields are set in the OCSF output generation. See the [OCSF output implementation](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/outputs/ocsf/ocsf.py) for reference. ### Validation Checklist Before releasing a new provider with `--push-to-cloud` support: * [ ] Verify `provider_uid` matches the UID used in the API to register the provider * [ ] Confirm `provider` field contains the correct provider name * [ ] Ensure all `finding_info.uid` values are unique across findings * [ ] Validate that `resources.uid` is populated for every finding > [!TIP] > > Use `python scripts/validate_ocsf_output.py output/*.ocsf.json` to automate these checks. ## Checklist for New Providers ### CLI Integration Only **Phase 1: Research & Planning** * [ ] Soft research completed * [ ] Spike date scheduled * [ ] Deeper research completed * [ ] Action plan created **Phase 2: Implementation** * [ ] Folder and files created in `prowler/providers/` * [ ] Provider class implemented and inherits from `Provider` * [ ] Authentication/session logic implemented * [ ] Arguments/flags mapped and documented * [ ] Outputs and metadata standardized * [ ] Registered in the CLI * [ ] Minimal usage example provided **Phase 3: Delivery** * [ ] PoC delivered * [ ] MVP delivered * [ ] Version 1 completed * [ ] QA and documentation completed * [ ] GA release ready ### API Integration * [ ] All CLI integration items completed * [ ] Provider added to `ProviderChoices` enum in API models * [ ] API serializers created/updated for the provider * [ ] API views support the new provider type * [ ] Provider credentials model supports the new provider * [ ] API endpoints tested and working * [ ] Provider-specific validation implemented * [ ] API tests created and passing ### UI Integration * TBD *** ## Next Steps * [How to add a new Service](./services) * [How to add new Checks](./checks) * [How to contribute](./introduction#contributing-to-prowler) # Prowler Studio Source: https://docs.prowler.com/developer-guide/prowler-studio **Prowler Studio is an AI workflow that ensures Claude Code follows Prowler's skills, guardrails, and best practices when creating new security checks.** What lands in the resulting pull request is consistent, tested, and ready for human review — not half-correct boilerplate that needs to be rewritten. > [!NOTE] > > **Contributor Tool**: Prowler Studio is a workflow for advanced contributors adding new Prowler security checks. It is not part of Prowler Cloud, Prowler Local Server, or Prowler CLI. > [!WARNING] > > **Preview Feature**: Prowler Studio is under active development and breaking changes are expected. Please report issues or share feedback on [GitHub](https://github.com/prowler-cloud/prowler-studio/issues) or in the [Slack community](https://goto.prowler.com/slack). > [card] [Prowler Studio Repository](https://github.com/prowler-cloud/prowler-studio) > > Clone the source code, install Prowler Studio, and explore the agent workflow in detail. ## The Problem Adding a new check to [Prowler](https://github.com/prowler-cloud/prowler) is more than writing detection logic. A correct check has to: * Match Prowler's exact service and check folder structure and naming conventions * Wire up metadata, severity, remediation, tests, and compliance mappings * Mirror the patterns used by the hundreds of existing checks in the same provider * Actually load when Prowler scans for available checks — silent structural mistakes are easy to make Asking a general-purpose AI assistant to do this usually means guessing. It misses conventions, skips tests, or invents structure that looks right but does not load. The result is a half-correct PR that needs to be reviewed line by line or rewritten. ## The Solution Prowler Studio enforces the workflow end-to-end. Describe the check once — a markdown ticket, a Jira issue, or a GitHub issue — and the workflow: 1. **Loads Prowler-specific skills into every agent.** Every step starts with the same context an experienced Prowler engineer would have in mind. See [AI Skills System](/developer-guide/ai-skills) for how skills are structured. 2. **Runs specialized agents in sequence.** Implementation → testing → compliance mapping → review → PR creation. Each agent has one job and a tight scope. 3. **Verifies as it goes.** The check must load in Prowler. Tests must pass. If something fails, the agent fixes it and re-runs (up to a bounded number of attempts) before moving on. 4. **Produces a complete pull request.** Branch, passing check, tests, compliance mappings, and a pull request waiting for human review. The result is a consistent starting point, every time, on every supported provider. ## Quick Start ### Install Prowler Studio requires [`uv`](https://docs.astral.sh/uv/getting-started/installation/) — see the official [installation guide](https://docs.astral.sh/uv/getting-started/installation/). ```bash theme={null} git clone https://github.com/prowler-cloud/prowler-studio cd prowler-studio uv sync source .venv/bin/activate ``` ### Describe the Check A ticket is a structured markdown description of the check to create. It is the only input the workflow needs; every agent (implementation, testing, compliance mapping, review, PR creation) uses it as the source of truth, so the more concrete it is, the closer the first PR will land to the desired outcome. The ticket can be supplied in three ways: * **Local markdown file** → `--ticket path/to/ticket.md` * **Jira issue** → `--jira-url https://...` (uses the issue body) * **GitHub issue** → `--github-url https://...` (uses the issue body) The content should follow the **New Check Request** template: * The local copy at [`check_ticket_template.md`](https://github.com/prowler-cloud/prowler-studio/blob/main/check_ticket_template.md) covers `--ticket` and Jira tickets. * A prefilled GitHub form is also available: [Create a New Check Request issue](https://github.com/prowler-cloud/prowler/issues/new?template=new-check-request.yml). Sections marked *Optional* can be skipped; everything else helps the agents make the right decisions. ### Run the Workflow From a local markdown ticket: ```bash theme={null} prowler-studio --ticket check_ticket.md ``` From a Jira ticket: ```bash theme={null} prowler-studio --jira-url https://mycompany.atlassian.net/browse/PROJ-123 ``` From a GitHub issue: ```bash theme={null} prowler-studio --github-url https://github.com/owner/repo/issues/123 ``` > [!NOTE] > > Provide exactly one of `--ticket`, `--jira-url`, or `--github-url`. Keep changes local (no push, no pull request): ```bash theme={null} prowler-studio -b feat/my-check --ticket check_ticket.md --local ``` ### What You Get After a successful run the working environment contains: * A new branch on a clean Prowler worktree containing the check, metadata, tests, and compliance mappings * A pull request opened against Prowler (skipped with `--local`) * A timestamped log file under `logs/` capturing every step the agents took ## CLI Options | Option | Short | Description | | - | - | - | | `--branch` | `-b` | Branch name (default: `feat/-` or `feat/`) | | `--ticket` | `-t` | Path to a markdown check ticket file | | `--jira-url` | `-j` | Jira ticket URL (e.g., `https://mycompany.atlassian.net/browse/PROJ-123`) | | `--github-url` | `-g` | GitHub issue URL (e.g., `https://github.com/owner/repo/issues/123`) | | `--working-dir` | `-w` | Working directory for the Prowler clone (default: `./working`) | | `--no-worktree` | | Legacy mode — work directly on the main clone instead of using worktrees | | `--cleanup-worktree` | | Remove the worktree after a successful pull request is created | | `--local` | | Keep changes local — skip push and pull request creation | ## Configuration Set these environment variables depending on the input source: | Variable | When Needed | Purpose | | - | - | - | | `GITHUB_TOKEN` | `--github-url` (recommended) | Higher GitHub API rate limits and access to private issues | | `JIRA_SITE_URL` | `--jira-url` | Jira site, e.g. `https://mycompany.atlassian.net` | | `JIRA_EMAIL` | `--jira-url` | Email of the Jira account used to fetch the ticket | | `JIRA_API_TOKEN` | `--jira-url` | API token for the Jira account | # Renaming Checks in Prowler Source: https://docs.prowler.com/developer-guide/renaming-checks To rename a check in Prowler, follow these steps when aligning with Check ID structure, fixing typos, or updating check logic that requires a new name. When changing a Check ID, update the following files: ## Update Check Folder Structure First, rename the check folder with the new check name. **Path:** `prowler/providers//services//` **Example:** ``` # Before prowler/providers/aws/services/inspector2/inspector2_findings_exist/ # After prowler/providers/aws/services/inspector2/inspector2_active_findings_exist/ ``` Next, rename the file that contains the check logic. Inside that file, also rename the class name to match the new check name. **Path:** `prowler/providers//services///.py` **Example:** ```python theme={null} # Before class inspector2_findings_exist(Check): def execute(self): findings = [] # ... check logic ... # After class inspector2_active_findings_exist(Check): def execute(self): findings = [] # ... check logic ... ``` Then, rename the file that contains the check metadata. Inside that file, add the old check name as an alias in the `CheckAliases` field and modify the `CheckID` to the new check name. **Path:** `prowler/providers//services///.metadata.json` **Example:** ```json theme={null} { "Provider": "aws", "CheckID": "inspector2_active_findings_exist", "CheckTitle": "Check if Inspector2 active findings exist", "CheckAliases": [ "inspector2_findings_exist" ], "CheckType": [], "ServiceName": "inspector2", "SubServiceName": "", "ResourceIdTemplate": "arn:aws:inspector2:region:account-id/detector-id", "Severity": "medium", "ResourceType": "Other", "Description": "This check determines if there are any active findings in your AWS account that have been detected by AWS Inspector2.", "Risk": "Without using AWS Inspector, you may not be aware of all the security vulnerabilities in your AWS resources.", "RelatedUrl": "https://docs.aws.amazon.com/inspector/latest/user/findings-understanding.html", "Remediation": { "Code": { "CLI": "", "NativeIaC": "", "Other": "https://www.trendmicro.com/cloudoneconformity/knowledge-base/aws/Inspector/amazon-inspector-findings.html", "Terraform": "" }, "Recommendation": { "Text": "Review the active findings from Inspector2", "Url": "https://docs.aws.amazon.com/inspector/latest/user/what-is-inspector.html" } }, "Categories": [], "DependsOn": [], "RelatedTo": [], "Notes": "" } ``` ## Update Test Files Second, rename the tests folder with the new check name. **Path:** `tests/providers//services//` **Example:** ``` # Before tests/providers/aws/services/inspector2/inspector2_findings_exist/ # After tests/providers/aws/services/inspector2/inspector2_active_findings_exist/ ``` Next, rename the test file that contains all the unit tests. Inside that file, rename all appearances of the old check name to the new check name. **Path:** `tests/providers//services///_test.py` **Example:** ```python theme={null} # Before from prowler.providers.aws.services.inspector2.inspector2_findings_exist.inspector2_findings_exist import ( inspector2_findings_exist, ) class Test_inspector2_findings_exist: def test_inspector2_no_findings(self): # ... test logic ... def test_inspector2_with_findings(self): # ... test logic ... # After from prowler.providers.aws.services.inspector2.inspector2_active_findings_exist.inspector2_active_findings_exist import ( inspector2_active_findings_exist, ) class Test_inspector2_active_findings_exist: def test_inspector2_no_findings(self): # ... test logic ... def test_inspector2_with_findings(self): # ... test logic ... ``` **Important:** Update all references to the old check name in the test file, including: * Import statements at the top of the file * Class name in the test class * Any function calls to the check * Any string references to the check name * Mock patches that reference the check **Complete example of all changes needed in test files:** ```python theme={null} # Before from prowler.providers.aws.services.inspector2.inspector2_findings_exist.inspector2_findings_exist import ( inspector2_findings_exist, ) class Test_inspector2_findings_exist: def test_inspector2_no_findings(self): # Mock setup with mock.patch( "prowler.providers.aws.services.inspector2.inspector2_findings_exist.inspector2_findings_exist.inspector2_client", inspector2_client, ): check = inspector2_findings_exist() result = check.execute() assert len(result) == 1 assert result[0].status == "PASS" assert "No active findings found" in result[0].status_extended # After from prowler.providers.aws.services.inspector2.inspector2_active_findings_exist.inspector2_active_findings_exist import ( inspector2_active_findings_exist, ) class Test_inspector2_active_findings_exist: def test_inspector2_no_findings(self): # Mock setup with mock.patch( "prowler.providers.aws.services.inspector2.inspector2_active_findings_exist.inspector2_active_findings_exist.inspector2_client", inspector2_client, ): check = inspector2_active_findings_exist() result = check.execute() assert len(result) == 1 assert result[0].status == "PASS" assert "No active findings found" in result[0].status_extended ``` ## Update Compliance Mappings Finally, rename all appearances of the old check name to the new check name inside any compliance framework where the check is mapped. * `prowler/compliance//.json` **Example:** ```json theme={null} { "Framework": "CIS", "Version": "2.0", "Provider": "AWS", "Description": "The CIS Amazon Web Services Foundations Benchmark provides prescriptive guidance for configuring security options for a subset of Amazon Web Services.", "Requirements": [ { "Id": "4.1", "Description": "Ensure a log metric filter and alarm exist for unauthorized API calls", "Checks": [ "inspector2_active_findings_exist" ], "Attributes": [ { "Section": "4 Logging and Monitoring", "Profile": "Level 1", "AssessmentStatus": "Automated", "Description": "Real-time monitoring of API calls can be achieved by directing CloudTrail Logs to CloudWatch Logs and establishing corresponding metric filters and alarms." } ] } ] } ``` The development compliance file may contain examples of the check being renamed. If so, modify this file as well: * `api/src/backend/api/fixtures/dev/7_dev_compliance.json` # Secret-Scanning Checks Source: https://docs.prowler.com/developer-guide/secret-scanning-checks [Added in:  5.32.0](https://github.com/prowler-cloud/prowler/releases/tag/5.32.0) Prowler scans audited resources for plaintext secrets using [Kingfisher](https://github.com/mongodb/kingfisher), an open-source secret-scanning engine that Prowler invokes as a subprocess. This guide explains the structure every secret-scanning check must follow to keep scanning correct and efficient on large accounts. > [!NOTE] > > Since Prowler 5.32.0 the secret-scanning checks scan with Kingfisher. Earlier versions used the `detect-secrets` library. ## Overview Secret detection runs through a single helper in `prowler/lib/utils/utils.py`: * **`detect_secrets_scan_batch(payloads, excluded_secrets=..., validate=...)`** scans many payloads in chunked subprocess invocations and returns a `{key: [findings]}` dictionary. To scan a single payload, pass a one-entry mapping (for example, `{0: data}`). Every Kingfisher invocation carries a fixed process-startup cost (around 100 ms). Scanning once per resource would spawn thousands of subprocesses on large accounts (for example, thousands of CloudWatch log groups). `detect_secrets_scan_batch` amortizes that cost: it writes each payload to a temporary file as it consumes them, runs one subprocess per chunk (500 payloads by default), and maps the findings back to each payload by key. ## The Batched Structure Every secret-scanning check follows three phases. ### Phase 1: Collect Define a generator that yields `(key, payload)` for each scannable unit. The generator builds payload strings only — it does not call Kingfisher. Lazy yielding keeps memory and temporary-disk usage bounded to a single chunk, which matters when an account holds thousands of resources. ### Phase 2: Batch Call `detect_secrets_scan_batch` once with the generator. The helper consumes it in chunks, runs Kingfisher per chunk, and returns the keys that produced findings mapped to their finding lists. ### Phase 3: Report Iterate the resources, look up the findings by key, and build one report per resource. Emit a finding for **every** iterated resource — never drop one silently. When a resource's payload cannot be prepared for scanning (for example, user data that fails to base64-decode or decompress), report it as `MANUAL` with a status explaining the scan could not inspect it, rather than omitting it or claiming `PASS`. ```python theme={null} from prowler.lib.check.models import Check, Check_Report_AWS from prowler.lib.utils.utils import ( annotate_verified_secrets, detect_secrets_scan_batch, ) from prowler.providers.aws.services.example.example_client import example_client class example_resource_no_secrets(Check): def execute(self): findings = [] excluded = example_client.audit_config.get("secrets_ignore_patterns", []) validate = example_client.audit_config.get("secrets_validate", False) resources = list(example_client.resources) # Phase 1: collect — builds strings only, no scan. def payloads(): for index, resource in enumerate(resources): if resource.scannable_data: yield index, serialize(resource) # Phase 2: batch — one call, chunked subprocesses. batch_results = detect_secrets_scan_batch( payloads(), excluded_secrets=excluded, validate=validate ) # Phase 3: report — look up findings by key. for index, resource in enumerate(resources): report = Check_Report_AWS(metadata=self.metadata(), resource=resource) report.status = "PASS" report.status_extended = f"No secrets found in {resource.name}." detect_secrets_output = batch_results.get(index) if detect_secrets_output: report.status = "FAIL" report.status_extended = ( f"Potential secret found in {resource.name} -> ..." ) annotate_verified_secrets(report, detect_secrets_output) findings.append(report) return findings ``` ## Choosing the Key The key maps each finding back to its source. Two shapes cover every check: * **One payload per resource:** use the resource index. This fits checks that serialize a single payload per resource, such as launch configurations, CloudFormation outputs, SSM documents, Step Functions definitions, and OpenStack metadata. * **Several payloads per resource:** use a `(resource_index, fragment)` tuple, where the fragment identifies the variable, log stream, container, file, or version. Phase 3 groups the per-fragment findings to build the resource report. This fits CloudWatch log streams, ECS containers, CodeBuild variables, Glue arguments, and Lambda code files. Derive the indices from the same `list(...)` of resources in both Phase 1 and Phase 3 so the order stays stable and the keys align. ## Preserving Per-Payload Results `detect_secrets_scan_batch` runs Kingfisher with `--no-dedup`, so a secret that appears in more than one payload is reported for each one. This reproduces the result of scanning each payload individually. Build payload strings exactly as a single scan would: serialize the same data and keep line ordering, because messages often map a finding's `line_number` back to a variable name or metadata key. ## Validation and Severity `detect_secrets_scan_batch` accepts `validate`, read from `secrets_validate` in the provider configuration or the `--scan-secrets-validate` flag. When enabled, Kingfisher confirms whether each secret is live, and confirmed secrets carry `is_verified: True`. After marking a report as `FAIL`, pass the findings to `annotate_verified_secrets(report, findings)`. When any secret is verified, the helper escalates the finding to critical severity and appends a note that the secret was confirmed live. Validation stays off by default because it sends the discovered secret to the provider API. ## Excluded Secrets `detect_secrets_scan_batch` applies `secrets_ignore_patterns` — regular expressions from the provider configuration — against each finding's source line and drops the matches, mirroring single-scan behavior. ## Testing To assert on the verified-secret path, mock `detect_secrets_scan_batch` in the check module and return the keyed dictionary. For a single resource scanned at index `0`: ```python theme={null} mock.patch( "prowler.providers.aws.services.example.example_resource_no_secrets.example_resource_no_secrets.detect_secrets_scan_batch", return_value={ 0: [{"type": "...", "line_number": 1, "is_verified": True}] }, ) ``` Most tests need no mock at all: they seed resources that contain example secrets and assert on the `FAIL` status and message, which exercises the real batched path. Refer to the [Testing](/developer-guide/unit-testing) documentation for the general structure. # Creating a New Security Compliance Framework in Prowler Source: https://docs.prowler.com/developer-guide/security-compliance-framework This guide explains how to add a new security compliance framework to Prowler, end to end. It covers directory layout, the two supported JSON schemas (universal and legacy), the Pydantic models that validate each framework, check mapping conventions, output formatting, local validation, testing, and the pull request process. ## Introduction A compliance framework in Prowler maps a public or custom control catalog (for example CIS, NIST 800-53, PCI DSS, HIPAA, ENS, CCC, DORA) to the security checks that Prowler already runs. Each requirement links to zero, one or more Prowler checks. When a scan executes, findings are aggregated per requirement to produce the compliance report rendered by Prowler CLI and Prowler Cloud. Prowler ships 85+ compliance frameworks across all providers. The catalog lives under `prowler/compliance//` (legacy, per-provider) or `prowler/compliance/` (universal, multi-provider). > [!WARNING] > > A compliance framework must represent the **complete state** of the source catalog. Every requirement defined by the framework has to be present in the JSON file, even when no Prowler check can automate it. In that case, leave the requirement's check list empty, but do not omit the requirement. > > Requirement coverage feeds the compliance percentage calculations and the metadata surfaces (dashboards, widgets, exports). Missing requirements skew those metrics and break the report as a faithful snapshot of the framework. ### Two Supported Schemas | Schema | When to use | File location | Discovered as | | - | - | - | - | | **Universal (recommended for new frameworks)** | Multi-provider frameworks, or single-provider frameworks that benefit from declarative table/PDF rendering | `prowler/compliance/.json` (top-level) | Available for **every** provider whose key appears in any `requirement.checks` dict | | **Legacy provider-specific** | Single-provider frameworks with framework-specific attribute classes already declared in the codebase (CIS, ENS, ISO 27001, etc.) | `prowler/compliance//__.json` | Available only under that provider | Auto-discovery happens in `get_bulk_compliance_frameworks_universal(provider)` (`prowler/lib/check/compliance_models.py`), which scans **both** the top-level `prowler/compliance/` directory and every per-provider sub-directory. Legacy frameworks are transparently converted to the universal `ComplianceFramework` model via `adapt_legacy_to_universal()` before being returned, so the rest of Prowler — CLI table rendering, CSV/OCSF outputs, PDF generation — works the same regardless of the source schema. > The legacy entry-point `Compliance.get_bulk(provider)` (used by older code paths) only scans per-provider sub-directories. Universal top-level files are picked up exclusively via the universal loader; this matters if you are wiring a new code path against the legacy API. For **new** frameworks, prefer the universal schema: it requires no Python code changes, supports multiple providers in a single file, and table/PDF rendering is driven entirely from declarative configuration inside the JSON. > All Pydantic models in `compliance_models.py` are imported from `pydantic.v1`. Subclasses you add for the legacy schema must use `from pydantic.v1 import BaseModel`. ### Prerequisites Before adding a new framework, complete the following checks: * **Verify the framework is not already supported.** Inspect `prowler/compliance/` and every `prowler/compliance//` for an existing JSON file matching the name and version. * **Confirm the required checks exist.** Every requirement that can be automated must point to one or more existing Prowler checks. For each missing check, implement it first by following the [Prowler Checks](/developer-guide/checks) guide. * **Review a reference framework.** Use an existing framework with a similar structure as your template: * Universal: `prowler/compliance/dora_2022_2554.json`, `prowler/compliance/csa_ccm_4.0.json`. * Legacy: `prowler/compliance/aws/cis_2.0_aws.json` (canonical CIS shape), `prowler/compliance/aws/ccc_aws.json`, `prowler/compliance/aws/ens_rd2022_aws.json`, `prowler/compliance/aws/nist_800_53_revision_5_aws.json`. ## Universal Compliance Framework ### Where the File Lives Place the file at the top level of the compliance directory: ``` prowler/compliance/.json ``` Examples in the repository: `prowler/compliance/csa_ccm_4.0.json`, `prowler/compliance/dora_2022_2554.json`. The file is auto-discovered — there is **no** need to register it in any `__init__.py`, modify `prowler/lib/outputs/`, or update any other Python module. The framework key Prowler CLI accepts via `--compliance` is the basename of the JSON file without `.json` (`dora_2022_2554.json` → `dora_2022_2554`). ### Top-Level Structure ```json theme={null} { "framework": "", "name": "", "version": "", "description": "", "icon": "", "attributes_metadata": [ /* see below */ ], "outputs": { /* see below — optional */ }, "requirements": [ /* see below */ ] } ``` A `provider` field at the top level is **optional**. The framework's effective provider list is derived by `ComplianceFramework.get_providers()` (`compliance_models.py`) from the union of all keys appearing in `requirement.checks` across all requirements; the explicit `provider` field is used **only as a fallback** when no requirement carries any `checks` key. This is what enables a single file (e.g. `dora_2022_2554.json`) to cover AWS today and add Azure / GCP / etc. tomorrow without restructuring. Provider keys inside `requirement.checks` must match the directory names under `prowler/providers/`. The valid keys at present are: `aws`, `azure`, `gcp`, `m365`, `kubernetes`, `iac`, `github`, `googleworkspace`, `alibabacloud`, `cloudflare`, `mongodbatlas`, `nhn`, `openstack`, `oraclecloud`, `llm`. Comparison in `supports_provider()` is case-insensitive, but lowercase is the convention used everywhere in the repository. ### `attributes_metadata` Declares the shape of the per-requirement `attributes` dict. When this field is present, the root validator `validate_attributes_against_metadata` (`compliance_models.py`) enforces the schema at load time and rejects: * Missing keys marked `required: true`. * Keys present in `attributes` but not declared in `attributes_metadata` (typo / drift guard). * Values that violate a declared `enum`. * Values whose Python type does not match a declared `int`, `float` or `bool`. The runtime type check **only** covers `int`, `float` and `bool`. For `str`, `list_str` and `list_dict` the type is documentation-only — non-conforming values won't fail validation. If `attributes_metadata` is omitted, **no per-requirement validation runs at all**. ```json theme={null} "attributes_metadata": [ { "key": "Pillar", "label": "Pillar", "type": "str", "required": true, "enum": [ "ICT Risk Management", "ICT-Related Incident Reporting", "Digital Operational Resilience Testing", "ICT Third-Party Risk Management", "Information Sharing" ], "output_formats": { "csv": true, "ocsf": true } }, { "key": "Article", "label": "Article", "type": "str", "required": true, "output_formats": { "csv": true, "ocsf": true } } ] ``` Per attribute: * `key` (required): attribute name as it will appear in `requirement.attributes`. * `label`: human-readable label used in CSV headers and PDF. * `type`: one of `str`, `int`, `float`, `bool`, `list_str`, `list_dict`. Defaults to `str`. * `enum`: optional list of allowed values; non-conforming values are rejected at load time. * `required`: if `true`, every requirement must include this key with a non-null value. * `enum_display` / `enum_order`: optional per-enum-value visual metadata (label, abbreviation, color, icon) and explicit ordering for PDF rendering. * `output_formats`: `{ "csv": , "ocsf": }` — toggles inclusion in each output format. Both default to `true`. ### `outputs` Optional. Controls how the framework is rendered in the console table and in the generated PDF report. Skipping it falls back to sensible defaults. ```json theme={null} "outputs": { "table_config": { "group_by": "Pillar" }, "pdf_config": { "language": "en", "primary_color": "#003399", "secondary_color": "#0055A5", "bg_color": "#F0F4FA", "group_by_field": "Pillar", "sections": [ "ICT Risk Management", "ICT-Related Incident Reporting", "..." ], "section_short_names": { "ICT Risk Management": "ICT Risk Mgmt" }, "charts": [ { "id": "pillar_compliance", "type": "horizontal_bar", "group_by": "Pillar", "title": "Compliance Score by Pillar", "y_label": "Pillar", "x_label": "Compliance %", "value_source": "compliance_percent", "color_mode": "by_value" } ], "filter": { "only_failed": true, "include_manual": false } } } ``` `table_config.group_by` must reference an attribute key declared in `attributes_metadata`. The same applies to `pdf_config.group_by_field` and to every `charts[].group_by`. For frameworks with weighted scoring (e.g. ThreatScore) declare `pdf_config.scoring` with `risk_field` / `weight_field` / `risk_boost_factor`. For column splitting (e.g. CIS Level 1 vs Level 2) use `table_config.split_by`. ### `requirements` ```json theme={null} "requirements": [ { "id": "DORA-Art5", "name": "Governance and organisation", "description": "Financial entities shall have a sound, comprehensive and well-documented ICT internal governance and control framework. ...", "attributes": { "Pillar": "ICT Risk Management", "Article": "Article 5", "ArticleTitle": "Governance and organisation" }, "checks": { "aws": [ "iam_avoid_root_usage", "iam_no_root_access_key", "iam_root_mfa_enabled" ], "azure": [], "gcp": [] } } ] ``` Per requirement: * `id` (required): unique identifier within the framework. * `description` (required): the requirement text as authored by the framework. * `name`: short title shown alongside the id. * `attributes`: flat dict; keys must conform to `attributes_metadata`. * `checks`: dict keyed by provider name (the same lowercase keys listed in the previous section). Each value is a list of Prowler check names that evidence this requirement for that provider. The list **may be empty** and the dict itself defaults to `{}` if omitted; either way the requirement is still loaded and listed by `--list-compliance-requirements`, it just has zero checks to execute. Note: there is **no automatic check-existence validation** at load time — referencing a non-existent check name will silently produce a requirement with no findings. Validate this yourself (see "Validating Your Framework" below). * `config_requirements`: optional list of configuration guardrails. Each entry asserts that a configurable check referenced by this requirement ran with a configuration strict enough to actually satisfy the requirement; otherwise the requirement is forced to FAIL. See [Configuration Guardrails for Requirements](#configuration-guardrails-for-requirements) for the full schema and semantics. In the universal schema the field name is lowercase (`config_requirements`); legacy files use `ConfigRequirements`. For MITRE-style frameworks, additional optional fields are available on the requirement: `tactics`, `sub_techniques`, `platforms`, `technique_url` (these are populated automatically when adapting a legacy MITRE JSON to the universal model). ### Multi-Provider Frameworks A single universal file can cover any number of providers. The framework appears under each provider's `--list-compliance` output as long as **at least one** requirement has that provider key in its `checks` dict. When extending an existing universal framework with a new provider, the only change required is editing `requirement.checks`: ```diff theme={null} "checks": { "aws": ["iam_avoid_root_usage", "iam_no_root_access_key"], + "azure": ["entra_policy_ensure_mfa_for_admin_roles"] } ``` No code changes, no new file, no registration step. ## Legacy Provider-Specific Compliance Framework The legacy schema is still fully supported and remains the format used by most frameworks shipped today (CIS, NIST, ISO 27001, FedRAMP, PCI DSS, GDPR, HIPAA, ENS, etc.). It binds a framework to a single provider and validates each requirement against a framework-specific Pydantic attribute class. The legacy schema spans **four layers** — a complete contribution must touch every layer that applies: * **Layer 1 — Schema validation:** the Pydantic models in `prowler/lib/check/compliance_models.py` define the canonical schema for each attribute shape. * **Layer 2 — JSON catalog:** the framework JSON file in `prowler/compliance//` lists every requirement and maps it to checks. * **Layer 3 — Output formatter:** the Python module in `prowler/lib/outputs/compliance//` builds the CSV row model, the per-provider transformer, and the CLI summary table. * **Layer 4 — Output dispatchers:** the dispatchers in `prowler/lib/outputs/compliance/compliance.py` and `prowler/lib/outputs/compliance/compliance_output.py` route findings to the right formatter based on the framework identifier. The universal schema collapses Layers 3 and 4 into declarative configuration inside the JSON — that is the main reason it is preferred for new contributions. ### Directory Structure and File Naming Compliance frameworks live at: ``` prowler/compliance//__.json ``` The filename conventions are: * All lowercase, words separated with underscores. * `` is a supported provider identifier (same lowercase list as the universal section above). * `` is optional but recommended. Omit only when the framework has no versioning (e.g. `ccc_aws.json`). * The file basename (without `.json`) is the framework key that Prowler CLI accepts via `--compliance`. Examples: * `prowler/compliance/aws/cis_2.0_aws.json` * `prowler/compliance/aws/nist_800_53_revision_5_aws.json` * `prowler/compliance/azure/ens_rd2022_azure.json` * `prowler/compliance/kubernetes/cis_1.10_kubernetes.json` * `prowler/compliance/aws/ccc_aws.json` The output formatter directory mirrors the framework name: ``` prowler/lib/outputs/compliance// ├── .py # CLI summary-table dispatcher ├── _.py # Per-provider transformer class ├── models.py # Pydantic CSV row model └── __init__.py ``` ### JSON Schema Reference Every legacy compliance file is a JSON document with the following top-level keys. `Framework`, `Name` and `Provider` are validated non-empty by the root validator `framework_and_provider_must_not_be_empty` (`compliance_models.py`). | Field | Type | Required | Description | | - | - | - | - | | `Framework` | string | Yes | Canonical framework identifier, for example `CIS`, `NIST-800-53-Revision-5`, `ENS`, `CCC`. | | `Name` | string | Yes | Human-readable framework name displayed by Prowler Cloud and Prowler Local Server. | | `Version` | string | Yes (recommended) | Framework version, e.g. `2.0`. See [Version Handling](#version-handling). | | `Provider` | string | Yes | Upper-cased provider identifier: `AWS`, `AZURE`, `GCP`, `KUBERNETES`, `M365`, `GITHUB`, `GOOGLEWORKSPACE`, and so on. | | `Description` | string | Yes | Short description of the framework's scope and purpose. | | `Requirements` | array | Yes | List of [requirement objects](#requirement-object). | #### Requirement Object Each entry in `Requirements` describes one control or requirement. | Field | Type | Required | Description | | - | - | - | - | | `Id` | string | Yes | Unique identifier within the framework, for example `1.10` or `CCC.Core.CN01.AR01`. | | `Name` | string | No | Optional human-readable name (frameworks like NIST distinguish control name from description). | | `Description` | string | Yes | Verbatim description from the source framework. | | `Attributes` | array | Yes | List of [attribute objects](#attribute-objects). The shape depends on the framework. | | `Checks` | array of strings | Yes | Prowler check identifiers that automate the requirement. Leave the list empty when the control cannot be automated. | | `ConfigRequirements` | array of objects | No | Optional [configuration guardrails](#configuration-guardrails-for-requirements). Each entry asserts that a configurable check ran with a configuration strict enough to satisfy the requirement; when it did not, the requirement is forced to FAIL. | #### Attribute Objects `Attributes` is parsed against the union declared in `Compliance_Requirement.Attributes` (`compliance_models.py`). Pydantic v1 tries each member of the union in declaration order and falls back to `Generic_Compliance_Requirement_Attribute` (the last entry) when nothing else matches — so a brand-new shape that doesn't match any existing class will silently be accepted as Generic, losing its specific fields. As of today, the registered attribute classes are: `CIS_Requirement_Attribute`, `ENS_Requirement_Attribute`, `ASDEssentialEight_Requirement_Attribute`, `ISO27001_2013_Requirement_Attribute`, `AWS_Well_Architected_Requirement_Attribute`, `KISA_ISMSP_Requirement_Attribute`, `Prowler_ThreatScore_Requirement_Attribute`, `CCC_Requirement_Attribute`, `C5Germany_Requirement_Attribute`, `CSA_CCM_Requirement_Attribute`, and `Generic_Compliance_Requirement_Attribute` (fallback). MITRE-style frameworks use the separate `Mitre_Requirement` model with `Tactics` / `SubTechniques` / `Platforms` / `TechniqueURL` at the requirement top level. The most common shapes are summarized below. ##### CIS\_Requirement\_Attribute Used by every CIS benchmark. | Field | Type | Required | Notes | | - | - | - | - | | `Section` | string | Yes | Top-level section, e.g. `1 Identity and Access Management`. | | `SubSection` | string | No | Optional second-level grouping. | | `Profile` | enum | Yes | One of `Level 1`, `Level 2`, `E3 Level 1`, `E3 Level 2`, `E5 Level 1`, `E5 Level 2`. | | `AssessmentStatus` | enum | Yes | `Manual` or `Automated`. | | `Description` | string | Yes | Control description. | | `RationaleStatement` | string | Yes | Reason the control exists. | | `ImpactStatement` | string | Yes | Impact of non-compliance. | | `RemediationProcedure` | string | Yes | Remediation steps. | | `AuditProcedure` | string | Yes | Audit steps. | | `AdditionalInformation` | string | Yes | Free-form notes. | | `DefaultValue` | string | No | Default configuration value, when relevant. | | `References` | string | Yes | Colon-separated list of reference URLs. | ##### ENS\_Requirement\_Attribute Used by the Spanish ENS (Esquema Nacional de Seguridad) frameworks. | Field | Type | Required | Notes | | - | - | - | - | | `IdGrupoControl` | string | Yes | Control group identifier. | | `Marco` | string | Yes | Framework block (`operacional`, `organizativo`, `proteccion`). | | `Categoria` | string | Yes | Control category. | | `DescripcionControl` | string | Yes | Control description in Spanish. | | `Tipo` | enum | Yes | `refuerzo`, `requisito`, `recomendacion`, `medida`. | | `Nivel` | enum | Yes | `opcional`, `bajo`, `medio`, `alto`. | | `Dimensiones` | array of enum | Yes | Subset of `confidencialidad`, `integridad`, `trazabilidad`, `autenticidad`, `disponibilidad`. | | `ModoEjecucion` | string | Yes | Execution mode (`manual`, `automático`, `híbrido`). | | `Dependencias` | array of strings | Yes | Ids of prerequisite controls. Empty list when none. | ##### CCC\_Requirement\_Attribute Used by the Common Cloud Controls Catalog. | Field | Type | Required | Notes | | - | - | - | - | | `FamilyName` | string | Yes | Control family, e.g. `Data`. | | `FamilyDescription` | string | Yes | Description of the family. | | `Section` | string | Yes | Section title. | | `SubSection` | string | Yes | Subsection title, or empty string. | | `SubSectionObjective` | string | Yes | Stated objective for the subsection. | | `Applicability` | array of strings | Yes | Applicability tags such as `tlp-green`, `tlp-amber`, `tlp-red`. | | `Recommendation` | string | Yes | Implementation recommendation. | | `SectionThreatMappings` | array of objects | Yes | Each entry has `ReferenceId` and `Identifiers`. | | `SectionGuidelineMappings` | array of objects | Yes | Each entry has `ReferenceId` and `Identifiers`. | ##### Generic\_Compliance\_Requirement\_Attribute The fallback attribute model used when no framework-specific schema applies (e.g. NIST 800-53, PCI DSS, GDPR, HIPAA). It is **always the last** element of the `Compliance_Requirement.Attributes` Union; that ordering is load-bearing. | Field | Type | Required | Notes | | - | - | - | - | | `ItemId` | string | No | Item identifier. | | `Section` | string | No | Section name. | | `SubSection` | string | No | Subsection name. | | `SubGroup` | string | No | Subgroup name. | | `Service` | string | No | Affected service, e.g. `iam`. | | `Type` | string | No | Control type. | | `Comment` | string | No | Free-form comment. | For the remaining attribute classes (`AWS_Well_Architected_Requirement_Attribute`, `ISO27001_2013_Requirement_Attribute`, `Mitre_Requirement_Attribute_`, `KISA_ISMSP_Requirement_Attribute`, `Prowler_ThreatScore_Requirement_Attribute`, `C5Germany_Requirement_Attribute`, `CSA_CCM_Requirement_Attribute`) consult `prowler/lib/check/compliance_models.py` for the full field sets. > [!NOTE] > > The `Attributes` field is a Pydantic `Union`. The generic attribute model **must** remain the last element of that Union — otherwise Pydantic v1 silently coerces every framework into the generic shape and your specialized fields are dropped. Adding a brand-new attribute shape requires inserting the Pydantic class **before** `Generic_Compliance_Requirement_Attribute`. #### Minimal Working Example The following snippet is a complete, valid framework file named `my_framework_1.0_aws.json`, saved at `prowler/compliance/aws/my_framework_1.0_aws.json`. It uses the generic attribute shape for simplicity. ```json title="prowler/compliance/aws/my_framework_1.0_aws.json" theme={null} { "Framework": "My-Framework", "Name": "My Framework 1.0 for AWS", "Version": "1.0", "Provider": "AWS", "Description": "Internal baseline for AWS accounts.", "Requirements": [ { "Id": "MF-1.1", "Description": "Root account must have multi-factor authentication enabled.", "Attributes": [ { "ItemId": "MF-1.1", "Section": "Identity and Access Management", "SubSection": "Root Account", "Service": "iam" } ], "Checks": [ "iam_root_mfa_enabled", "iam_root_hardware_mfa_enabled" ] }, { "Id": "MF-2.1", "Description": "S3 buckets must block public access at the account level.", "Attributes": [ { "ItemId": "MF-2.1", "Section": "Data Protection", "Service": "s3" } ], "Checks": [ "s3_account_level_public_access_blocks" ] } ] } ``` ### Mapping Checks to Requirements Each requirement links to the Prowler checks that, together, produce a PASS or FAIL verdict for that control. * **Include every requirement from the source catalog.** The framework file must mirror the full control list, one-to-one. Compliance percentages, dashboards, and exported metadata are computed against the total requirement count. * List every check by its canonical identifier — the value of `CheckID` inside the check's `.metadata.json` file. * One requirement can reference multiple checks. The requirement is evaluated as FAIL when any referenced check produces a FAIL finding for a resource in scope. * Leave `Checks` (legacy) or `checks.` (universal) as an empty array when the requirement cannot be automated. The requirement still appears in the report and contributes to the total. * Reuse checks across requirements when the same control applies in multiple places. Do not duplicate check logic to match framework structure. * Avoid referencing checks from a different provider. A legacy compliance file is bound to one provider, and cross-provider checks will never match findings in the scan. To discover available checks: ```bash theme={null} uv run python prowler-cli.py --list-checks ``` ### Supporting Multiple Providers (Legacy) The legacy schema binds each file to a single provider. To cover several providers with the same framework, ship one JSON file per provider: ``` prowler/compliance/aws/cis_2.0_aws.json prowler/compliance/azure/cis_2.0_azure.json prowler/compliance/gcp/cis_2.0_gcp.json ``` Keep the `Framework` and `Version` values identical across the files so the dispatcher matches them; change only the `Provider`, `Checks`, and provider-specific metadata. The CIS output formatter already supports every provider listed above. For a brand-new framework that spans several providers, **prefer the universal schema** — it covers every provider from a single file. If you must use the legacy schema, add one transformer per provider in `prowler/lib/outputs/compliance//` and extend the summary-table dispatcher accordingly. See [Output Formatter](#output-formatter). ### Output Formatter Legacy frameworks render in two forms: a detailed CSV report written to disk, and a summary table printed in the CLI. Both are produced by the output formatter package for the framework. Universal frameworks do **not** need a Python output formatter — the `outputs` config inside the JSON drives rendering — so this section applies only to the legacy schema. For a new legacy framework named `my_framework`, create: ``` prowler/lib/outputs/compliance/my_framework/ ├── __init__.py ├── my_framework.py # CLI summary table dispatcher ├── my_framework_aws.py # Per-provider transformer └── models.py # CSV row Pydantic model ``` #### Step 1 — Define the CSV Row Model In `models.py`, declare a Pydantic v1 model with one field per CSV column. Use existing models such as `AWSCISModel` in `prowler/lib/outputs/compliance/cis/models.py` as the reference. Fields typically include `Provider`, `Description`, `AccountId`, `Region`, `AssessmentDate`, `Requirements_Id`, `Requirements_Description`, one `Requirements_Attributes_*` field per attribute key, plus the finding fields `Status`, `StatusExtended`, `ResourceId`, `ResourceName`, `CheckId`, `Muted`, `Framework`, `Name`. #### Step 2 — Implement the Transformer In `my_framework_aws.py`, subclass `ComplianceOutput` from `prowler.lib.outputs.compliance.compliance_output` and implement `transform(findings, compliance, compliance_name)`. Iterate over `findings`, match each finding to the requirements it satisfies through `finding.compliance.get(compliance_name, [])`, and append one row per attribute to `self._data`. #### Step 3 — Add the Summary-Table Dispatcher In `my_framework.py`, implement `get_my_framework_table(findings, bulk_checks_metadata, compliance_framework, output_filename, output_directory, compliance_overview)` following the pattern in `prowler/lib/outputs/compliance/cis/cis.py`. #### Step 4 — Register the Framework in the Dispatchers * Add the dispatcher call in `prowler/lib/outputs/compliance/compliance.py`, inside `display_compliance_table`, with a branch such as `elif "my_framework" in compliance_framework:`. * Register the CSV model and transformer in `prowler/lib/outputs/compliance/compliance_output.py` so the CSV file is emitted during the scan. > [!NOTE] > > For NIST-style catalogs that use `Generic_Compliance_Requirement_Attribute`, no custom formatter is needed. The generic formatter in `prowler/lib/outputs/compliance/generic/` handles them automatically, provided the JSON validates against the generic attribute schema. ### Legacy-to-Universal Adapter At load time, every legacy file is transparently adapted to a `ComplianceFramework` via `adapt_legacy_to_universal()` (`compliance_models.py`), which: (a) flattens the first element of `Attributes` into a flat `attributes` dict, (b) wraps `Checks` as `{provider_lower: [...]}`, (c) infers `attributes_metadata` from the matched Pydantic class via `_infer_attribute_metadata()`. The rest of Prowler (CSV/OCSF/PDF output, CLI table) then treats both formats identically. Loader-error behaviour differs between the two entry points: * `load_compliance_framework()` (legacy) is **fail-fast**: it calls `sys.exit(1)` on any `ValidationError` (`compliance_models.py`). * `load_compliance_framework_universal()` is more lenient — it logs the error and returns `None`, so `get_bulk_compliance_frameworks_universal()` simply skips the broken file and keeps loading the rest. ## Configuration Guardrails for Requirements [Added in:  5.32.0](https://github.com/prowler-cloud/prowler/releases/tag/5.32.0) Some requirements are only truly satisfied when the configurable checks behind them ran with a configuration strict enough to meet the control. A [configurable check](/developer-guide/configurable-checks) reads thresholds from the scan's `audit_config`, so loosening a value can make the check PASS while the requirement it backs is, in fact, not satisfied. A worked example: CIS AWS 6.0 requirement 2.11 ("credentials unused for 45 days or more are disabled") maps to `iam_user_accesskey_unused`, which is driven by the `max_unused_access_keys_days` config key. If a user raises that value to `120`, the check passes for a key unused for 90 days — yet the requirement explicitly demands a 45-day threshold, so the PASS is misleading. Configuration guardrails close that gap. A requirement declares the configuration it expects, and when the scan ran with a configuration too loose to honor it, the requirement is forced to **FAIL** in every compliance output, with the reason surfaced in the finding's extended status. > [!NOTE] > > Guardrails are an **optional** safety net for configurable checks. A requirement that maps only to non-configurable checks does not need them. When the field is absent, behavior is unchanged. ### Where Guardrails Are Declared The field is attached to each requirement and exists in both schemas: * **Legacy** (`prowler/compliance//...`): `ConfigRequirements`, a list of objects, validated against the `Compliance_Requirement_ConfigConstraint` Pydantic model (`prowler/lib/check/compliance_models.py`). * **Universal** (`prowler/compliance/...`): `config_requirements`, the same list of objects as plain dicts on `UniversalComplianceRequirement`. When a legacy file is adapted to the universal model, `adapt_legacy_to_universal()` copies `ConfigRequirements` into `config_requirements` (`compliance_models.py`), so downstream code only ever reads one shape. ### Constraint Schema Each entry in the list is a single constraint with the following fields: | Field | Type | Required | Description | | - | - | - | - | | `Check` | string | Yes | The configurable check this constraint guards. Should be one of the requirement's `Checks`. Used only to build a human-readable reason. | | `ConfigKey` | string | Yes | The `audit_config` key the check reads (for example `max_unused_access_keys_days`). | | `Operator` | enum | Yes | How to compare the applied value against `Value`. One of `lte`, `gte`, `eq`, `in`, `subset`, `superset`. | | `Value` | bool, int, float, string, or list | Yes | The strictest configuration the requirement tolerates. The accepted Python type depends on the operator (see below). | | `Provider` | string | No | The provider this constraint applies to (e.g. `aws`). **Required for universal (multi-provider) frameworks**, where the same requirement maps checks across providers — the constraint is only evaluated when the scanned provider matches. Single-provider (legacy) frameworks omit it. | ### Operators | Operator | Applied value satisfies the guardrail when… | Typical use | | - | - | - | | `lte` | `applied <= Value` | Maximum-age / maximum-count thresholds (e.g. `max_unused_access_keys_days <= 45`). | | `gte` | `applied >= Value` | Minimum-retention / minimum-count thresholds. | | `eq` | `applied == Value` | Boolean toggles or an exact required value (e.g. `mute_non_default_regions == false`). | | `in` | `applied` is one of `Value` (a list) | The applied scalar must belong to an allowed set. | | `subset` | `set(applied) <= set(Value)` | **Allowlist** configs — every applied value must already be permitted. Widening the allowlist with a weaker value (e.g. adding TLS `1.0` to `recommended_minimal_tls_versions`) breaks the guardrail. | | `superset` | `set(applied) >= set(Value)` | **Denylist** configs — every forbidden value must remain forbidden. Removing an entry from a denylist (e.g. dropping a weak algorithm from `insecure_key_algorithms`) breaks the guardrail. | > [!NOTE] > > `subset` / `superset` require both the applied value and `Value` to be lists; any other type is treated as not satisfied. For `eq` against a boolean, declare `Value` as a JSON boolean (`false`, not `0`) — the model keeps booleans distinct from integers. ### How Guardrails Are Evaluated All evaluation lives in one shared module, `prowler/lib/check/compliance_config_eval.py`, consumed by every compliance output (CSV, OCSF, and the CLI tables) and reused by the Prowler API backend so the rule is defined exactly once. 1. The applied configuration is the scan-global `audit_config` (the same mapping for every resource and region), resolved via `get_scan_audit_config()`. 2. For each requirement that declares constraints, `evaluate_config_constraints()` walks the list and returns `(is_compliant, reason)`. The requirement is compliant when **every** explicitly-set key satisfies its constraint. 3. A constraint tagged with a `Provider` that does **not** match the provider being scanned (resolved via `get_scan_provider_type()`) is **skipped**. This scopes a universal framework's constraints to the right provider, so a guardrail authored for an AWS check never affects a GCP or Azure scan of the same requirement. Untagged constraints (legacy single-provider frameworks) always apply. 4. A constraint whose `ConfigKey` is **not present** in `audit_config` is **skipped** — the check's built-in default is assumed to already match what the requirement expects. This is why nothing changes for the default configuration. 5. When a constraint is violated, the finding's status is overridden to `FAIL` and a plain-language explanation is prepended to `status_extended` (via `apply_config_status()`). The message opens with `Configuration not valid for this requirement.` and names the check, the value the scan applied, what the requirement needs and how to fix it. For the table generators, `get_effective_status()` applies the same FAIL roll-up so per-section counts stay consistent. > [!WARNING] > > Guardrails only ever make a result **stricter** (they can turn PASS into FAIL); they never relax a real FAIL into PASS. A requirement with no constraints, or whose keys all use defaults, is reported exactly as before. ### Example: Legacy Framework From `prowler/compliance/aws/cis_6.0_aws.json`, requirement 2.11 declares two guardrails — one per configurable check it maps to: ```json title="prowler/compliance/aws/cis_6.0_aws.json" theme={null} { "Id": "2.11", "Description": "Ensure credentials unused for 45 days or more are disabled.", "Checks": [ "iam_user_accesskey_unused", "iam_user_console_access_unused" ], "ConfigRequirements": [ { "Check": "iam_user_accesskey_unused", "ConfigKey": "max_unused_access_keys_days", "Operator": "lte", "Value": 45 }, { "Check": "iam_user_console_access_unused", "ConfigKey": "max_console_access_days", "Operator": "lte", "Value": 45 } ], "Attributes": [ /* ... */ ] } ``` A boolean guardrail from the same file: requirement 2.5 (IAM Access Analyzer) only holds when regions are not muted, so a scan with `mute_non_default_regions: true` cannot be trusted for it: ```json theme={null} "ConfigRequirements": [ { "Check": "accessanalyzer_enabled", "ConfigKey": "mute_non_default_regions", "Operator": "eq", "Value": false } ] ``` ### Example: Universal Framework The universal schema uses the lowercase `config_requirements` key with the identical object shape: ```json theme={null} { "id": "MF-2.1", "name": "Restrict TLS to modern versions", "description": "Endpoints must negotiate only TLS 1.2 or higher.", "checks": { "aws": ["elbv2_listener_ssl_listeners"] }, "config_requirements": [ { "Check": "elbv2_listener_ssl_listeners", "Provider": "aws", "ConfigKey": "recommended_minimal_tls_versions", "Operator": "subset", "Value": ["TLS 1.2", "TLS 1.3"] } ] } ``` Each constraint declares the `Provider` it targets so the guardrail is only evaluated on scans of that provider — essential for universal frameworks like CSA CCM and DORA, where one requirement maps checks across `aws`, `azure`, `gcp` and more. Because the operator is `subset`, adding `"TLS 1.0"` to `recommended_minimal_tls_versions` widens the allowlist beyond `["TLS 1.2", "TLS 1.3"]` and the requirement is forced to FAIL. ### What the User Sees With a loosened config, the affected requirement's findings report: ```text theme={null} Status: FAIL StatusExtended: Configuration not valid for this requirement. The check iam_user_accesskey_unused has max_unused_access_keys_days set to 120, but the requirement needs a value of 45 or lower. Update it to 45 or lower. ``` The same `Configuration not valid for this requirement.` message appears identically across the CSV, OCSF, and console-table outputs. ### Authoring Guidelines * Declare a guardrail only for keys whose value actually changes whether the requirement is met. Most configurable checks do not need one. * Set `Value` to the **strictest** configuration the control tolerates — the same number the control text cites (CIS 45 days, NIST ≤90, and so on). * Keep `ConfigKey` spelled exactly as the check reads it from `audit_config`; an unknown key is never present in the config and the constraint is silently skipped. * In a **universal (multi-provider) framework**, always set `Provider` to the provider that owns `Check` — otherwise the guardrail would leak onto scans of the other providers the requirement maps. Legacy single-provider files omit it. * Pick the operator from the value's role: a max threshold is `lte`, a min threshold is `gte`, a toggle is `eq`, an allowlist is `subset`, a denylist is `superset`. * An unrecognized operator does **not** block the requirement — a malformed constraint is treated as satisfied rather than failing the whole framework. Validate your JSON with the tests below. ### Testing Guardrails The shared evaluator and the per-output integration are covered by: * `tests/lib/check/compliance_config_eval_test.py` — operator semantics, skipped-key behavior, and the FAIL override. * `tests/lib/check/compliance_config_constraint_model_test.py` — model validation (types, operator enum, bool-vs-int). * `tests/lib/check/compliance_config_requirements_data_test.py` — sanity-checks the guardrails shipped in the JSON catalog. * Per-output tests under `tests/lib/outputs/compliance/` (CIS AWS/Azure, ENS AWS, OCSF, universal table) confirm the override reaches each format. Run them with: ```bash theme={null} uv run pytest -n auto \ tests/lib/check/compliance_config_eval_test.py \ tests/lib/check/compliance_config_constraint_model_test.py \ tests/lib/check/compliance_config_requirements_data_test.py \ tests/lib/outputs/compliance/ ``` ## Version Handling Prowler matches frameworks by concatenating `Framework` and `Version`. A missing or empty `Version` collapses several frameworks to the same key and breaks CLI filtering with `--compliance`. * Always set `Version` (or `version` for universal frameworks) to a non-empty string, even for frameworks that rename editions rather than version them. Use the edition identifier (for example `RD2022`, `v2025.10`, `4.0`, `2022/2554`). * When the source catalog has no version, use the first year of adoption or the release date. * For **legacy** files, make sure the version substring embedded in the filename matches `Version`, because the CLI dispatcher reads `compliance_framework.split("_")[1]` to select the correct version. ## Validating Your Framework Before opening a PR, validate the JSON loads cleanly against the model and that every referenced check actually exists. ### 1. Schema Validation For **universal** frameworks, load the file and inspect what was parsed. The framework key inside `bulk` is the **basename of the JSON file** (without `.json`); for `prowler/compliance/dora_2022_2554.json` that key is `dora_2022_2554`, for `prowler/compliance/aws/cis_5.0_aws.json` it is `cis_5.0_aws`. ```python theme={null} from prowler.lib.check.compliance_models import ( load_compliance_framework_universal, get_bulk_compliance_frameworks_universal, ) fw = load_compliance_framework_universal("prowler/compliance/.json") assert fw is not None, "load returned None — check the logs for the validation error" print(fw.framework, len(fw.requirements), fw.get_providers()) bulk = get_bulk_compliance_frameworks_universal("aws") assert "" in bulk ``` ### 2. Check Existence Cross-Check There is **no automatic check-existence validation** at load time. Cross-check that every check name in your framework maps to a real check directory: ```python theme={null} import os real = set() for svc in os.listdir("prowler/providers/aws/services"): svc_path = f"prowler/providers/aws/services/{svc}" if not os.path.isdir(svc_path): continue for entry in os.listdir(svc_path): if os.path.isfile(f"{svc_path}/{entry}/{entry}.metadata.json"): real.add(entry) referenced = {c for r in fw.requirements for c in r.checks.get("aws", [])} missing = referenced - real assert not missing, f"checks referenced in framework but not found in repo: {sorted(missing)}" ``` ### 3. CLI Smoke Test ```bash theme={null} uv run python prowler-cli.py --list-compliance ``` The framework must appear in the output. A validation error indicates a schema mismatch. ```bash theme={null} uv run python prowler-cli.py \ --compliance \ --log-level ERROR ``` Verify that: * Prowler produces a CSV file under `output/compliance/` with the expected name. * The CLI summary table lists every section / pillar of the framework. * Findings roll up under the expected requirements. ### 4. Inspect the CSV Output Open the generated CSV and confirm: * All columns defined in `models.py` (legacy) or in `attributes_metadata` (universal) appear. * Every requirement has at least one row per scanned resource (when there are findings). * Attribute values such as `Requirements_Attributes_Section` reflect the JSON content. ### 5. Verify the Framework in Prowler Local Server Launch Prowler Local Server (`docker compose up` from the repository root) and run a scan with the new compliance framework. Confirm the compliance page renders the requirements, sections, and status widgets correctly. ## Testing Compliance contributions require two layers of tests. * **Schema tests** exercise the Pydantic models. Extend `tests/lib/check/universal_compliance_models_test.py` with a case that loads the new JSON file and asserts the attribute type matches the expected model. * **Output tests** (legacy frameworks only) exercise the transformer. Mirror the structure under `tests/lib/outputs/compliance//` with fixtures that feed synthetic findings through the transformer and assert the resulting CSV rows. Run the suite with: ```bash theme={null} uv run pytest -n auto tests/lib/check/universal_compliance_models_test.py \ tests/lib/outputs/compliance/ ``` For guidance on writing Prowler SDK tests, refer to [Unit Testing](/developer-guide/unit-testing). ## Running and Listing Your Framework Once the file is in place, the CLI auto-discovers it: ```sh theme={null} prowler --list-compliance # framework appears in the list prowler --compliance --list-checks prowler --compliance # full scan + compliance report prowler --compliance --list-compliance-requirements ``` For end-user-facing tutorials (recommended for high-profile frameworks), add a dedicated page under `docs/user-guide/compliance/tutorials/` and register it in the `"Compliance"` group of `docs/docs.json`. See `docs/user-guide/compliance/tutorials/threatscore.mdx` as a reference. ## Submitting the Pull Request Before opening the pull request: 1. Run the complete QA pipeline: ```bash theme={null} uv run pre-commit run --all-files uv run pytest -n auto ``` 2. Add a changelog fragment `prowler/changelog.d/.added.md`, describing the new framework and the providers it covers (no PR link in the text; it is attached automatically at release time). 3. Follow the [Pull Request Template](https://github.com/prowler-cloud/prowler/blob/master/.github/pull_request_template.md) and set the PR title using Conventional Commits, e.g. `feat(compliance): add My Framework 1.0 for AWS`. 4. Request review from the compliance codeowners listed in `.github/CODEOWNERS`. ## Troubleshooting The following issues are the most common when contributing a compliance framework. * **`ValidationError: field required` during scan (legacy).** The JSON is missing a required attribute field. Re-check the matching Pydantic model in `prowler/lib/check/compliance_models.py`. * **All attributes collapse to `Generic_Compliance_Requirement_Attribute` values (legacy).** The Pydantic `Union` is ordered incorrectly, or the JSON matches only the generic shape. Keep the generic model in the last Union position and ensure every required field is present in the JSON. * **`attributes_metadata validation failed` (universal).** The root validator in `compliance_models.py` rejected the file. The error message lists each offending requirement; common causes are unknown attribute keys (typo or missing entry in `attributes_metadata`), enum violations, or missing required keys. * **`--compliance` filter does not find the framework.** For legacy: the filename does not match `__.json`, the version is empty, or the file lives outside `prowler/compliance//`. For universal: the file is not at the top level of `prowler/compliance/` or it loaded as `None` (check logs for the validation error). * **CLI summary table is empty but the CSV is populated (legacy).** The dispatcher branch in `prowler/lib/outputs/compliance/compliance.py` is missing or its substring match does not catch the framework key. * **CSV file is missing after the scan (legacy).** The transformer class is not registered in `prowler/lib/outputs/compliance/compliance_output.py`, or `transform()` raises silently. Run the scan with `--log-level DEBUG`. * **Findings do not roll up under a requirement.** A check listed in `Checks` either does not exist for that provider or is spelled incorrectly. Run `--list-checks | grep ` to confirm, or run the check-existence cross-check from "Validating Your Framework". ## Reference Examples Use the following files as templates when modeling a new contribution. * `prowler/compliance/dora_2022_2554.json` — universal schema, single-provider populated (AWS), ready to extend with more providers. * `prowler/compliance/csa_ccm_4.0.json` — universal schema, multi-provider populated (AWS, Azure, GCP, AlibabaCloud, OracleCloud). * `prowler/compliance/aws/cis_2.0_aws.json` — legacy CIS attribute shape. * `prowler/compliance/aws/nist_800_53_revision_5_aws.json` — legacy generic attribute shape. * `prowler/compliance/aws/ccc_aws.json` — legacy CCC attribute shape. * `prowler/compliance/azure/ens_rd2022_azure.json` — legacy ENS attribute shape. * `prowler/lib/check/compliance_models.py` — canonical Pydantic schemas for both formats. * `prowler/lib/outputs/compliance/cis/` — reference implementation of a multi-provider legacy output formatter. * `prowler/lib/outputs/compliance/generic/` — reference implementation of a legacy generic output formatter. # Server-Sent Events (SSE) Source: https://docs.prowler.com/developer-guide/server-sent-events [Added in:  1.32.0](https://github.com/prowler-cloud/prowler/releases/tag/1.32.0) This guide explains how to add a **Server-Sent Events (SSE)** endpoint to the Prowler API. SSE lets the backend push a one-way stream of events to a client over a single long-lived HTTP connection — ideal for live progress, token-by-token LLM output, or any "the server has news for you" use case where the client should not poll. > [!NOTE] > > The platform ships the SSE **infrastructure** (`api.sse`) and wiring. No feature endpoint streams over SSE out of the box — this guide shows how to build one on top of the shared base. ## When to Use SSE | Need | Use | | - | - | | Server pushes incremental updates, client only reads | **SSE** | | Bidirectional, low-latency messaging (chat both ways, games) | WebSocket | | Client asks, server answers once | Plain REST | SSE is the right tool when the **client only consumes**: scan progress, long-running job checkpoints, streamed LLM tokens, cross-client resource-sync notifications. It rides on plain HTTP, reconnects automatically in the browser via the native [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) API, and needs no extra protocol. ## How It Works SSE is wired through [`django-eventstream`](https://github.com/fanout/django_eventstream) and a small platform layer in `api/src/backend/api/sse/`: | Piece | File | Responsibility | | - | - | - | | `BaseSSEViewSet` | `api/sse/base_views.py` | Base DRF viewset a feature subclasses. The feature implements `get_channels`; the base handles auth, the tenant transaction, and delegates streaming to `django-eventstream`. | | `SSEChannelManager` | `api/sse/channelmanager.py` | Registered in `settings.EVENTSTREAM_CHANNELMANAGER_CLASS`. Reads the channel set off the request and enforces the platform-wide tenant gate. | | `SSEAuthentication` | `api/authentication.py` | Same JWT/API-key stack as the rest of the API, plus an `?access_token=` fallback for browser `EventSource` clients. Lives with the other authentication classes, not in the `sse` package. | | `make_channel_name` / `tenant_id_from_channel` | `api/sse/utils.py` | Single source of truth for the channel-name format, so publishers and the channel manager agree byte-for-byte. | | Settings | `config/settings/eventstream.py` | Valkey Pub/Sub backend (dedicated DB), channel manager, allowed headers. | ### Transport: The Server Runs on ASGI SSE connections are long-lived. Holding one open per synchronous worker would exhaust the worker pool, so the API runs under Gunicorn's native **`asgi` worker** (`config.asgi:application`). Streams are parked on the event loop while ordinary CRUD endpoints keep their synchronous execution (Django runs sync views in a thread-sensitive executor under ASGI). This is configured in `config/guniconf.py` and used by both the dev and production entrypoints — no separate server process is needed. ### The Data Flow ``` publisher (Celery task / view) subscriber (browser, CLI) │ │ │ send_event(channel, "scan.progress", …) │ GET …/event-stream ▼ ▼ Valkey Pub/Sub ◄────────────────────► BaseSSEViewSet.list (EVENTSTREAM_VALKEY_DB) → get_channels() (RLS-scoped) → SSEChannelManager (tenant gate) → StreamingHttpResponse (text/event-stream) ``` A publisher anywhere in the system (most often a Celery task) calls `send_event(channel, event_type, payload)`. `django-eventstream` fans it out over Valkey Pub/Sub to every connection subscribed to that channel. ## Adding an SSE Endpoint to Your Feature The example below streams progress for a long-running **scan**. Adapt the resource, prefix, and event names to your feature. **1. Pick a channel prefix** Channels follow the format `::`, built only through `make_channel_name`. The prefix is owned by your feature and may contain hyphens but **never colons** (the parser splits on `:`). ```python theme={null} CHANNEL_PREFIX = "scan-progress" ``` The tenant id is baked into every channel name. That is what lets the platform enforce cross-tenant isolation without knowing anything about your feature. **2. Subclass BaseSSEViewSet** Create the viewset for the SSE sub-resource. The only required method is `get_channels`; it runs inside the tenant transaction set up by the base class, so any database lookup inside it is automatically RLS-scoped. ```python theme={null} # scans/event_streams.py from api.sse import BaseSSEViewSet, make_channel_name from django.shortcuts import get_object_or_404 from scans.models import Scan CHANNEL_PREFIX = "scan-progress" class ScanEventStreamViewSet(BaseSSEViewSet): def get_queryset(self): # RLS already scopes to the tenant; narrow further as needed # (e.g. only scans the requesting user may see). return Scan.objects.filter(tenant_id=self.request.tenant_id) def get_channels(self) -> set[str]: scan = get_object_or_404(self.get_queryset(), pk=self.kwargs["scan_pk"]) return {make_channel_name(CHANNEL_PREFIX, scan.tenant_id, scan.id)} ``` > [!WARNING] > > `get_channels` **must raise** the relevant DRF exception (`NotFound`, `PermissionDenied`, `NotAuthenticated`) when authorization fails — `get_object_or_404` does this for you. Returning an empty set surfaces as django-eventstream's confusing "No channels specified" error instead of the real cause. **3. Wire the URL as a sub-resource** Mount the endpoint as an `event-stream` sub-resource. Keep it **outside the DRF router**, which would force the URL into a list/detail convention. Route the `get` method to the viewset's `list` action. ```python theme={null} # scans/urls.py path( "scans//event-stream", ScanEventStreamViewSet.as_view({"get": "list"}), name="scan-event-stream", ), ``` **4. Define your event vocabulary** A feature owns its event types in `//events.py`: one `publish_` function per event type, each body a **single** `send_event` call so the wire-level string lives in exactly one place. ```python theme={null} # scans/events.py from django_eventstream import send_event def publish_progress(channel: str, checked: int, total: int) -> None: send_event(channel, "scan.progress", {"checked": checked, "total": total}) def publish_end(channel: str, scan_id: str) -> None: # Terminal event carries the canonical id so reconnecting clients # can refetch the persisted resource over REST. send_event(channel, "scan.end", {"scan_id": scan_id}) def publish_error(channel: str, code: str, detail: str) -> None: send_event(channel, "scan.error", {"code": code, "detail": detail}) ``` There is no platform-side enum, registry, or dispatch table — **the naming convention is the contract** (see below). **5. Publish from the producer** Wherever the work happens — usually a Celery task — build the channel the same way and publish: ```python theme={null} from api.sse import make_channel_name from scans.events import publish_progress, publish_end channel = make_channel_name("scan-progress", scan.tenant_id, scan.id) publish_progress(channel, checked=42, total=100) ... publish_end(channel, scan_id=str(scan.id)) ``` ## Event Naming Convention Every event uses an event type of the form **`.`** (lowercased, dot-separated). The verb comes from this platform-wide vocabulary — if you need a verb that is not listed, document the addition in this guide so the catalog stays discoverable. | Verb | When to use | | - | - | | `delta` | An incremental piece of a stream the client concatenates (LLM text tokens, audio chunks). Standard term across OpenAI / Anthropic / LiteLLM / Vercel AI SDK. | | `start` | Begin marker for a compound operation (e.g. a tool call whose execution will be reported by a matching `end`). | | `end` | Terminal marker. Carries the canonical resource id so reconnecting clients can refetch persisted state via REST. | | `progress` | Periodic checkpoint with quantifiable completion, e.g. `{"checked": 42, "total": 100}`. | | `created` / `updated` / `deleted` | Resource-lifecycle events for cross-client sync streams. | | `error` | Terminal failure. Carries a stable `code` for client switching and a human-readable `detail`. | > [!NOTE] > > Payloads are **flat JSON**. The wire-level `event:` field already names the event type, so do **not** wrap the payload in `{"type": ..., "data": ...}`. Include the canonical resource UUID on terminal events so reconnecting clients can reconcile via REST. ## Authentication SSE endpoints use the same authentication stack as the rest of the API. Non-browser clients (CLI, programmatic) send the standard `Authorization` header — JWT or API key. Browser `EventSource` is the only widely available SSE client API and it **cannot set custom headers**. For that case only, the endpoint accepts a JWT via the `?access_token=` query parameter. The header always wins when present — a header is intentional, while a query parameter can leak into referers and logs, so it is consulted only as a fallback. ```javascript theme={null} // Browser const es = new EventSource( `/api/v1/scans/${scanId}/event-stream?access_token=${jwt}` ); ``` ```bash theme={null} # CLI / programmatic — header, exactly like every other endpoint curl -N -H "Authorization: Bearer $JWT" \ https:///api/v1/scans/$SCAN_ID/event-stream ``` ## Tenant Isolation & Security Model Authorization is enforced at two layers: 1. **At connect**, `get_channels` runs under the regular DRF stack inside the tenant transaction (`rls_transaction`). Resource lookups are RLS-scoped, so a user cannot even resolve a channel for a resource they cannot see. Narrow the queryset further (e.g. `created_by=request.user`) when a resource is per-user within a tenant. 2. **After connect**, `SSEChannelManager.can_read_channel` re-verifies tenant membership by parsing the tenant id embedded in the channel name. Cross-tenant subscription is rejected even if a URL-level check ever has a bug. A malformed channel name is treated as "not authorized". Because the tenant id lives inside the channel name, this gate works for any feature without the platform knowing anything about it. ## Reconnect & State Recovery The platform deliberately ships **without server-side replay** (`is_channel_reliable` returns `False`). When a client reconnects, it does **not** receive missed events. Instead: * Terminal events (`*.end`) carry the canonical resource **UUID**. * On reconnect, the client refetches the authoritative state from the normal REST endpoint using that id. Design your event payloads accordingly: deltas are ephemeral and concatenated in-flight; the durable truth always lives behind a REST resource. ## Local Development * The dev and production entrypoints both launch Gunicorn with the `asgi` worker (`config.asgi:application`). In dev, `DJANGO_DEBUG=True` enables hot reload; `preload_app` is automatically disabled under debug so edited code is picked up. * SSE uses a **dedicated Valkey database** (`EVENTSTREAM_VALKEY_DB`, default `2`) kept separate from the Celery broker so a noisy broker cannot crowd out streaming traffic. It reuses the same `VALKEY_*` connection settings as the rest of the platform. | Env var | Default | Purpose | | - | - | - | | `EVENTSTREAM_VALKEY_DB` | `2` | Valkey DB index for the SSE Pub/Sub bus | | `DJANGO_WORKER_CLASS` | `asgi` | Gunicorn worker class | Test the stream end to end with `curl -N` (disable buffering) and an auth header: ```bash theme={null} curl -N -H "Authorization: Bearer $JWT" \ http://localhost:8080/api/v1/scans/$SCAN_ID/event-stream ``` ## Testing The platform basis is covered by `api/tests/test_sse.py` (channel parsing, the tenant gate, and auth precedence). For a feature endpoint, test: * `get_channels` returns the expected channel for an authorized resource and raises `NotFound`/`PermissionDenied` otherwise. * Each `publish_` helper emits the correct event type and flat payload (mock `send_event`). * The producer builds the channel with `make_channel_name` using the resource's own `tenant_id`. # Prowler Services Source: https://docs.prowler.com/developer-guide/services Here you can find how to create a new service, or to complement an existing one, for a [Prowler Provider](/developer-guide/provider). > [!NOTE] > > First ensure that the provider you want to add the service is already created. It can be checked [here](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers). If the provider is not present, please refer to the [Provider](./provider.md) documentation to create it from scratch. ## Introduction In Prowler, a **service** represents a specific solution or resource offered by one of the supported [Prowler Providers](/developer-guide/provider), for example, [EC2](https://aws.amazon.com/ec2/) in AWS, or [Microsoft Exchange](https://www.microsoft.com/en-us/microsoft-365/exchange/exchange-online) in M365. Services are the building blocks that allow Prowler to interact directly with the various resources exposed by each provider. Each service is implemented as a class that encapsulates all the logic, data models, and API interactions required to gather and store information about that service's resources. All of this data is used by the [Prowler checks](/developer-guide/checks) to generate the security findings. ## Adding a New Service To create a new service, a new folder must be created inside the specific provider following this pattern: `prowler/providers//services//`. Within this folder the following files are also to be created: * `__init__.py` (empty) – Ensures Python recognizes this folder as a package. * `_service.py` – Contains all the logic and API calls of the service. * `_client.py` – Contains the initialization of the freshly created service's class so that the checks can use it. Once the files are created, you can check that the service has been created by running the following command: `uv run python prowler-cli.py --list-services | grep `. ## Service Structure and Initialisation The Prowler's service structure is as outlined below. To initialise it, just import the service client in a check. ### Service Base Class All Prowler provider services should inherit from a common base class to avoid code duplication. This base class handles initialization and storage of functions and objects needed across services. The exact implementation depends on the provider's API requirements, but the following are the most common responsibilities: * Initialize/store clients to interact with the provider's API. * Store the audit and fixer configuration. * Implement threading logic where applicable. For reference, the base classes for each provider can be checked here: * [AWS Service Base Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/lib/service/service.py) * [GCP Service Base Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/gcp/lib/service/service.py) * [Azure Service Base Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/azure/lib/service/service.py) * [Kubernetes Service Base Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/kubernetes/lib/service/service.py) * [M365 Service Base Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/m365/lib/service/service.py) * [GitHub Service Base Class](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/github/lib/service/service.py) ### Service Class Due to the complexity and differences across provider APIs, the following example demonstrates best practices for structuring a service in Prowler. File `_service.py`: ```python title="Example Service Class" theme={null} from datetime import datetime from typing import Optional # To use the Pydantic's BaseModel. from pydantic import BaseModel # Prowler logging library. from prowler.lib.logger import logger # Provider parent class. from prowler.providers..lib.service.service import ServiceParentClass # Create a class for the Service. class (ServiceParentClass): def __init__(self, provider: Provider): """Initialize the Service Class Args: provider: Prowler Provider object. """ # Call Service Parent Class __init__. # The __class__.__name__ is used to obtain it automatically. # From the Service Class name, but a custom one can be passed. # String in case the provider's API service name is different. super().__init__(__class__.__name__, provider) # Create an empty dictionary of items to be gathered, using the unique ID as the dictionary's key, e.g., instances. self. = {} # If parallelization can be carried out by regions or locations, the function __threading_call__ to be used must be implemented in the Service Parent Class. # If it is not implemented, you can make it in a sequential way, just calling the function. self.__threading_call__(self.__describe___) # If it is needed you can create another function to retrieve more data from the items. # Here we are using the second parameter of the __threading_call__ function to create one thread per item. # You can also make it sequential without using the __threading_call__ function iterating over the items inside the function. self.__threading_call__(self.__describe___, self..values()) # In case of use the __threading_call__ function, you have to pass the regional_client to the function, as a parameter. def __describe___(self, regional_client): """Get all and store in the self. dictionary Args: regional_client: Regional client object. """ logger.info(" - Describing ...") # A try-except block must be created in each function. try: # If pagination is supported by the provider, is always better to use it, call to the provider API to retrieve the desired data. describe__paginator = regional_client.get_paginator("describe_") # Paginator to get every item. for page in describe__paginator.paginate(): # Another try-except within the for loop to continue iterating in case something unexpected happens. try: for in page[""]: # Adding Retrieved Resources to the Object # Once the resource has been retrieved, it must be included in the previously created object to ensure proper data handling within the service. self.[] = ( arn=stack[""], name=stack[""], tags=stack.get("Tags", []), region=regional_client.region, ) except Exception as error: logger.error( f"{} -- {error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) # Logging Errors in Exception Handling # When handling exceptions, use the following approach to log errors appropriately based on the cloud provider being used: except Exception as error: # Depending on each provider we can must use different fields in the logger, e.g.: AWS: regional_client.region or self.region, GCP: project_id and location, Azure: subscription logger.error( f"{} -- {error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) def __describe___(self, item: ): """Get details for a Args: item: Item object. """ logger.info(" - Describing to get specific details...") # A try-except block must be created in each function. try: _details = self.regional_clients[.region].describe_( =.name ) # E.g., check if item is Public. This case is important: if values are being retrieved from a dictionary, the function "dict.get()" must be used with a default value in case this value is not present. .public = _details.get("Public", False) except Exception as error: # Fields for logging errors with relevant item information, e.g.: AWS: .region, GCP: .project_id, Azure: .region logger.error( f"{.region} -- {error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) ``` > [!NOTE] > > To prevent false findings, when Prowler fails to retrieve items due to Access Denied or similar errors, the affected item's value is set to `None`. #### Resource Models Resource models define structured classes used within services to store and process data extracted from API calls. They are defined in the same file as the service class, but outside of the class, usually at the bottom of the file. Prowler leverages Pydantic's [BaseModel](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel) to enforce data validation. ```python title="Service Model" theme={null} # Implementation Approach # Each service class should include custom model classes using Pydantic's BaseModel for the resources being audited. class (BaseModel): """ holds a """ id: str """[].id""" name: str """[].name""" region: str """[].region""" public: bool """[].public""" # Optional attributes can be created set to None by default. tags: Optional[list] """[].tags""" ``` #### Service Attributes *Optimized Data Storage with Python Dictionaries* Each group of resources within a service should be structured as a Python [dictionary](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) to enable efficient lookups. The dictionary lookup operation has [O(1) complexity](https://en.wikipedia.org/wiki/Big_O_notation#Orders_of_common_functions), and lookups are constantly executed. *Assigning Unique Identifiers* Each dictionary key must be a unique ID to identify the resource in a univocal way. Example: ```python theme={null} self.virtual_machines = {} self.virtual_machines["vm-01234567890abcdef"] = VirtualMachine() ``` ### Service Client Each Prowler service requires a service client to use the service in the checks. The following is the `_client.py` file, which contains the initialization of the freshly created service's class so that service checks can use it. This file is almost the same for all the services among the providers: ```python theme={null} from prowler.providers.common.provider import Provider from prowler.providers..services.._service import _client = (Provider.get_global_provider()) ``` ## Provider Permissions in Prowler Before implementing a new service, verify that Prowler's existing permissions for each provider are sufficient. If additional permissions are required, refer to the relevant documentation and update accordingly. Provider-Specific Permissions Documentation: * [AWS](/user-guide/providers/aws/authentication#required-permissions) * [Azure](/user-guide/providers/azure/authentication#required-permissions) * [GCP](/user-guide/providers/gcp/authentication#required-permissions) * [M365](/user-guide/providers/microsoft365/authentication#required-permissions) * [GitHub](/user-guide/providers/github/authentication) ## Service Architecture and Cross-Service Communication ### Core Principle: Service Isolation with Client Communication Each service must contain **ONLY** the information unique to that specific service. When a check requires information from multiple services, it must use the **client objects** of other services rather than directly accessing their data structures. This architecture ensures: * **Loose coupling** between services * **Clear separation of concerns** * **Maintainable and testable code** * **Consistent data access patterns** ### Cross-Service Communication Pattern Instead of services directly accessing each other's internal data, checks should import and use client objects: **❌ INCORRECT - Direct data access:** ```python theme={null} # DON'T DO THIS from prowler.providers.aws.services.cloudtrail.cloudtrail_service import cloudtrail_service from prowler.providers.aws.services.s3.s3_service import s3_service class cloudtrail_bucket_requires_mfa_delete(Check): def execute(self): # WRONG: Directly accessing service data for trail in cloudtrail_service.trails.values(): for bucket in s3_service.buckets.values(): # Direct access violates separation of concerns ``` **✅ CORRECT - Client-based communication:** ```python theme={null} # DO THIS INSTEAD from prowler.providers.aws.services.cloudtrail.cloudtrail_client import cloudtrail_client from prowler.providers.aws.services.s3.s3_client import s3_client class cloudtrail_bucket_requires_mfa_delete(Check): def execute(self): # CORRECT: Using client objects for cross-service communication for trail in cloudtrail_client.trails.values(): trail_bucket = trail.s3_bucket for bucket in s3_client.buckets.values(): if trail_bucket == bucket.name: # Use bucket properties through s3_client if bucket.mfa_delete: # Implementation logic ``` ### Real-World Example: CloudTrail + S3 Integration This example demonstrates how CloudTrail checks validate S3 bucket configurations: ```python theme={null} from prowler.lib.check.models import Check, Check_Report_AWS from prowler.providers.aws.services.cloudtrail.cloudtrail_client import cloudtrail_client from prowler.providers.aws.services.s3.s3_client import s3_client class cloudtrail_bucket_requires_mfa_delete(Check): def execute(self): findings = [] if cloudtrail_client.trails is not None: for trail in cloudtrail_client.trails.values(): if trail.is_logging: trail_bucket_is_in_account = False trail_bucket = trail.s3_bucket # Cross-service communication: CloudTrail check uses S3 client for bucket in s3_client.buckets.values(): if trail_bucket == bucket.name: trail_bucket_is_in_account = True if bucket.mfa_delete: report.status = "PASS" report.status_extended = f"Trail {trail.name} bucket ({trail_bucket}) has MFA delete enabled." # Handle cross-account scenarios if not trail_bucket_is_in_account: report.status = "MANUAL" report.status_extended = f"Trail {trail.name} bucket ({trail_bucket}) is a cross-account bucket or out of Prowler's audit scope, please check it manually." findings.append(report) return findings ``` **Key Benefits:** * **CloudTrail service** only contains CloudTrail-specific data (trails, configurations) * **S3 service** only contains S3-specific data (buckets, policies, ACLs) * **Check logic** orchestrates between services using their public client interfaces * **Cross-account detection** is handled gracefully when resources span accounts ### Service Consolidation Guidelines **When to combine services in the same file:** Implement multiple services as **separate classes in the same file** when two services are **practically the same** or one is a **direct extension** of another. **Example: S3 and S3Control** S3Control is an extension of S3 that provides account-level controls and access points. Both are implemented in `s3_service.py`: ```python theme={null} # File: prowler/providers/aws/services/s3/s3_service.py class S3(AWSService): """Standard S3 service for bucket operations""" def __init__(self, provider): super().__init__(__class__.__name__, provider) self.buckets = {} self.regions_with_buckets = [] # S3-specific initialization self._list_buckets(provider) self._get_bucket_versioning() # ... other S3-specific operations class S3Control(AWSService): """S3Control service for account-level and access point operations""" def __init__(self, provider): super().__init__(__class__.__name__, provider) self.account_public_access_block = None self.access_points = {} # S3Control-specific initialization self._get_public_access_block() self._list_access_points() # ... other S3Control-specific operations ``` **Separate client files:** ```python theme={null} # File: prowler/providers/aws/services/s3/s3_client.py from prowler.providers.aws.services.s3.s3_service import S3 s3_client = S3(Provider.get_global_provider()) # File: prowler/providers/aws/services/s3/s3control_client.py from prowler.providers.aws.services.s3.s3_service import S3Control s3control_client = S3Control(Provider.get_global_provider()) ``` **When NOT to consolidate services:** Keep services separate when they: * **Operate on different resource types** (EC2 vs RDS) * **Have different authentication mechanisms** (different API endpoints) * **Serve different operational domains** (IAM vs CloudTrail) * **Have different regional behaviors** (global vs regional services) ### Cross-Service Dependencies Guidelines **1. Always use client imports:** ```python theme={null} # Correct pattern from prowler.providers.aws.services.service_a.service_a_client import service_a_client from prowler.providers.aws.services.service_b.service_b_client import service_b_client ``` **2. Handle missing resources gracefully:** ```python theme={null} # Handle cross-service scenarios resource_found_in_account = False for external_resource in other_service_client.resources.values(): if target_resource_id == external_resource.id: resource_found_in_account = True # Process found resource break if not resource_found_in_account: # Handle cross-account or missing resource scenarios report.status = "MANUAL" report.status_extended = "Resource is cross-account or out of audit scope" ``` **3. Document cross-service dependencies:** ```python theme={null} class check_with_dependencies(Check): """ Check Description Dependencies: - service_a_client: For primary resource information - service_b_client: For related resource validation - service_c_client: For policy analysis """ ``` ## Regional Service Implementation When implementing services for regional providers (like AWS, Azure, GCP), special considerations are needed to handle resource discovery across multiple geographic locations. This section provides a complete guide using AWS as the reference example. ### Regional vs Non-Regional Services **Regional Services:** Require iteration across multiple geographic locations where resources may exist (e.g., EC2 instances, VPC, RDS databases). **Non-Regional/Global Services:** Operate at a global or tenant level without regional concepts (e.g., IAM users, Route53 hosted zones). ### AWS Regional Implementation Example AWS is the perfect example of a regional provider. Here's how Prowler handles AWS's regional architecture: ```python theme={null} # File: prowler/providers/aws/services/ec2/ec2_service.py class EC2(AWSService): def __init__(self, provider): super().__init__(__class__.__name__, provider) self.instances = {} self.security_groups = {} # Regional resource discovery across all AWS regions self.__threading_call__(self._describe_instances) self.__threading_call__(self._describe_security_groups) def _describe_instances(self, regional_client): """Discover EC2 instances in a specific region""" try: describe_instances_paginator = regional_client.get_paginator("describe_instances") for page in describe_instances_paginator.paginate(): for reservation in page["Reservations"]: for instance in reservation["Instances"]: # Each instance includes its region self.instances[instance["InstanceId"]] = Instance( id=instance["InstanceId"], region=regional_client.region, state=instance["State"]["Name"], # ... other properties ) except Exception as error: logger.error(f"Failed to describe instances in {regional_client.region}: {error}") ``` #### Regional Check Execution ```python theme={null} # File: prowler/providers/aws/services/ec2/ec2_instance_public_ip/ec2_instance_public_ip.py class ec2_instance_public_ip(Check): def execute(self): findings = [] # Automatically iterates across ALL AWS regions where instances exist for instance in ec2_client.instances.values(): report = Check_Report_AWS(metadata=self.metadata(), resource=instance) report.region = instance.region # Critical: region attribution report.resource_arn = f"arn:aws:ec2:{instance.region}:{instance.account_id}:instance/{instance.id}" if instance.public_ip: report.status = "FAIL" report.status_extended = f"Instance {instance.id} in {instance.region} has public IP {instance.public_ip}" else: report.status = "PASS" report.status_extended = f"Instance {instance.id} in {instance.region} does not have a public IP" findings.append(report) return findings ``` #### Key AWS Regional Features **Region-Specific ARNs:** ``` arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0 arn:aws:s3:eu-west-1:123456789012:bucket/my-bucket arn:aws:rds:ap-southeast-2:123456789012:db:my-database ``` **Parallel Processing:** * Each region processed independently in separate threads * Failed regions don't affect other regions * User can filter specific regions: `-f us-east-1` **Global vs Regional Services:** * **Regional**: EC2, RDS, VPC (require region iteration) * **Global**: IAM, Route53, CloudFront (single `us-east-1` call) This architecture allows Prowler to efficiently scan AWS accounts with resources spread across multiple regions while maintaining performance and error isolation. ### Regional Service Best Practices 1. **Use Threading for Regional Discovery**: Leverage the `__threading_call__` method to parallelize resource discovery across regions 2. **Store Region Information**: Always include region metadata in resource objects for proper attribution 3. **Handle Regional Failures Gracefully**: Ensure that failures in one region don't affect others 4. **Optimize for Performance**: Use paginated calls and efficient data structures for large-scale resource discovery 5. **Support Region Filtering**: Allow users to limit scans to specific regions for focused audits ## Best Practices * When available in the provider, use threading or parallelization utilities for all methods that can be parallelized to maximize performance and reduce scan time. * Define a Pydantic `BaseModel` for every resource you manage, and use these models for all resource data handling. * Log every major step (start, success, error) in resource discovery and attribute collection for traceability and debugging; include as much context as possible. * Catch and log all exceptions, providing detailed context (region, subscription, resource, error type, line number) to aid troubleshooting. * Use consistent naming for resource containers, unique identifiers, and model attributes to improve code readability and maintainability. * Add docstrings to every method and comments to explain any service-specific logic, especially where provider APIs behave differently or have quirks. * Collect and store resource tags and additional attributes to support richer checks and reporting. * Leverage shared utility helpers for session setup, identifier parsing, and other cross-cutting concerns to avoid code duplication. This kind of code is typically stored in a `lib` folder in the service folder. * Keep code modular, maintainable, and well-documented for ease of extension and troubleshooting. * **Each service should contain only information unique to that specific service** - use client objects for cross-service communication. * **Handle cross-account and missing resources gracefully** when checks span multiple services. # StackIT Provider Source: https://docs.prowler.com/developer-guide/stackit-details This page details the [StackIT Cloud](https://www.stackit.de/) provider implementation in Prowler. By default, Prowler audits a single StackIT project per scan. To configure it, provide the project ID and either a service account key file path or inline service account key JSON. ## StackIT Provider Classes Architecture The StackIT provider implementation follows the general [Provider structure](/developer-guide/provider). This section focuses on the StackIT-specific implementation, highlighting how the generic provider concepts are realized for StackIT in Prowler. For a full overview of the provider pattern, base classes, and extension guidelines, see [Provider documentation](/developer-guide/provider). ### `StackitProvider` (Main Class) * **Location:** [`prowler/providers/stackit/stackit_provider.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/stackit/stackit_provider.py) * **Base Class:** Inherits from `Provider` (see [base class details](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/common/provider.py)). * **Purpose:** Central orchestrator for StackIT-specific logic, API authentication, credential validation, and configuration. * **Key StackIT Responsibilities:** * Initializes StackIT SDK authentication via a service account key file or inline service account key JSON. The SDK mints and refreshes access tokens internally. * Validates the service account credentials and project ID (UUID format validation). * Loads and manages configuration, mutelist, and fixer settings. * Provides properties and methods for downstream StackIT service classes to access credentials, identity, and configuration data. ### Data Models * **Location:** [`prowler/providers/stackit/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/stackit/models.py) * **Purpose:** Define structured data for StackIT identity and output configuration. * **Key StackIT Models:** * `StackITIdentityInfo`: Holds StackIT identity metadata, including project ID and project name (fetched automatically from Resource Manager API). * `StackITOutputOptions`: Customizes default output filenames so StackIT reports include the audited project ID. * IaaS resource models such as `SecurityGroup` and `SecurityGroupRule` are defined in the IaaS service module. ### StackIT Services * **Location:** [`prowler/providers/stackit/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/stackit/services) * **Purpose:** Implement StackIT service clients and resource collection logic following the generic [service pattern](/developer-guide/services#service-base-class). * **Current Implementation:** The `IaaSService` collects security groups, rules, and network interface usage across supported StackIT regions. ### Exception Handling * **Location:** [`prowler/providers/stackit/exceptions/exceptions.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/stackit/exceptions/exceptions.py) * **Purpose:** Custom exception classes for StackIT-specific error handling, such as credential validation, API connection, and configuration errors. * **Key Exception Classes:** * `StackITBaseException`: Base exception for all StackIT provider errors. * `StackITCredentialsError`: Raised when credentials are invalid or missing. * `StackITInvalidProjectIdError`: Raised when project ID is invalid or not in UUID format. * `StackITAPIError`: Raised when StackIT API calls fail. ## Authentication ### Service Account Creation and Key Generation StackIT uses service account keys for API authentication. Service account keys are RSA key-pair based and provide secure, short-lived access tokens. ### Creating a Service Account Key #### Method 1: Via StackIT Portal 1. **Navigate to Service Accounts** * Go to the [StackIT Portal](https://portal.stackit.cloud/) * Select your project * Click **Service Accounts** in the left sidebar 2. **Create or Select Service Account** * If you don't have a service account, click **Create Service Account** * Provide a name and description * Assign necessary permissions: * For IaaS security checks: `iaas.viewer` or `project.owner` * For comprehensive audits: `project.owner` 3. **Generate Service Account Key** * Select your service account * Navigate to **Service Account Keys** * Click **Create key** * Choose one of the following options: * **STACKIT-generated key pair** (Recommended): Let STACKIT automatically generate an RSA key-pair * **User-provided key pair**: Upload your own RSA 2048 public key 4. **Download and Save the Key** * Download the generated service account key file (JSON format) * **Important**: Save the key securely - it contains your private key and will only be available once * Store the key file in a secure location (e.g., `~/.stackit/sa_key.json`) #### Method 2: Via StackIT CLI ```bash theme={null} # Install STACKIT CLI (if not already installed) # Follow instructions at: https://github.com/stackitcloud/stackit-cli # Create service account key (STACKIT-generated) stackit service-account key create --email my-service-account@example.com # Or create with your own RSA 2048 public key # First, generate your RSA key pair: openssl genrsa -out private-key.pem 2048 openssl rsa -in private-key.pem -pubout -out public-key.pem # Then create the key with your public key: stackit service-account key create \ --email my-service-account@example.com \ --public-key "$(cat public-key.pem)" ``` ### Finding Your Project ID Your StackIT project ID is a UUID that can be found: 1. In the StackIT Portal URL when viewing your project: `https://portal.stackit.cloud/projects/{PROJECT_ID}/...` 2. In the project settings page 3. Using the StackIT CLI: `stackit project list` ### Passing the Service Account Key to Prowler Prowler accepts the service account credentials in two equivalent forms; both go through the same StackIT SDK flow and refresh access tokens internally. #### Option 1: Key File Path (key persisted on disk) ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" export STACKIT_PROJECT_ID="12345678-1234-1234-1234-123456789abc" prowler stackit ``` Or as CLI flags: ```bash theme={null} prowler stackit \ --stackit-service-account-key-path ~/.stackit/sa-key.json \ --stackit-project-id 12345678-1234-1234-1234-123456789abc ``` #### Option 2: Inline Key Content (CI/CD, secret managers) ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY="$(vault kv get -field=key stackit/sa)" export STACKIT_PROJECT_ID="12345678-1234-1234-1234-123456789abc" prowler stackit ``` Prefer the environment variable over the matching `--stackit-service-account-key` CLI flag; passing the secret on the command line leaks it through process listings and shell history. ### Credential Lookup Order Prowler resolves credentials in this order: 1. **Command-line arguments**: * `--stackit-service-account-key` * `--stackit-service-account-key-path` * `--stackit-project-id` 2. **Environment variables**: * `STACKIT_SERVICE_ACCOUNT_KEY` * `STACKIT_SERVICE_ACCOUNT_KEY_PATH` * `STACKIT_PROJECT_ID` When both the inline key and the key file path are set, the inline content takes precedence. ## Configuration ### Command-Line Arguments StackIT-specific command-line arguments: | Argument | Description | Required | Default | | - | - | - | - | | `--stackit-service-account-key-path` | Path to a StackIT service account key JSON file | Yes\* | `$STACKIT_SERVICE_ACCOUNT_KEY_PATH` | | `--stackit-service-account-key` | Inline JSON content of a StackIT service account key (preferred env var: `STACKIT_SERVICE_ACCOUNT_KEY`) | Yes\* | `$STACKIT_SERVICE_ACCOUNT_KEY` | | `--stackit-project-id` | StackIT project ID (UUID format) | Yes\* | `$STACKIT_PROJECT_ID` | | `--stackit-region` | StackIT region(s) to scan | No | All available regions | \* Required unless provided via environment variables. ### Input Validation The StackIT provider performs comprehensive input validation: * **Service Account Credentials**: * At least one of `service_account_key_path` (file path) or `service_account_key` (inline JSON) must be supplied; both empty raises `StackITNonExistentTokenError` * When both are provided the inline content takes precedence * The key file path is logged as-is; the inline content is redacted in the credentials box * **Project ID**: * Must not be empty * Must be a valid UUID format (e.g., `12345678-1234-1234-1234-123456789abc`) * Validated using Python's UUID constructor Invalid credentials will result in clear error messages before any API calls are made. ## Available Services ### IaaS (Infrastructure as a Service) * **Service Class:** `IaaSService` * **Location:** [`prowler/providers/stackit/services/iaas/iaas_service.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/stackit/services/iaas/iaas_service.py) * **SDK:** Uses the [stackit-iaas](https://pypi.org/project/stackit-iaas/) Python SDK * **Purpose:** Manages IaaS resources including security groups, servers, and network interfaces. **Supported Resources:** * Security Groups and Rules * Servers (Virtual Machines) * Network Interfaces (NICs) **Key Features:** * Automatic discovery of all security groups in the project * Security rule parsing with support for unrestricted access detection * Network interface analysis to determine whether security groups are in use * By default, reports only security groups attached to at least one NIC; `--scan-unused-services` includes unused security groups too ## Available Checks The StackIT provider currently implements 4 security checks focused on network security: ### 1. iaas\_security\_group\_ssh\_unrestricted * **Severity:** High * **Description:** Detects security groups that allow unrestricted SSH access (port 22) from the internet. * **Risk:** Unrestricted SSH access increases the attack surface and risk of brute-force attacks. * **Detection Logic:** * Checks for ingress rules allowing TCP port 22 * Flags rules with `ip_range=None` or `ip_range="0.0.0.0/0"` or `ip_range="::/0"` * Reports security groups attached to NICs by default, or all security groups when `--scan-unused-services` is enabled ### 2. iaas\_security\_group\_rdp\_unrestricted * **Severity:** High * **Description:** Detects security groups that allow unrestricted RDP access (port 3389) from the internet. * **Risk:** Unrestricted RDP access enables potential unauthorized remote desktop access. * **Detection Logic:** * Checks for ingress rules allowing TCP port 3389 * Flags unrestricted IP ranges (None, 0.0.0.0/0, ::/0) * Reports security groups attached to NICs by default, or all security groups when `--scan-unused-services` is enabled ### 3. iaas\_security\_group\_database\_unrestricted * **Severity:** High * **Description:** Detects security groups that allow unrestricted access to common database ports. * **Monitored Ports:** * MySQL: 3306 * PostgreSQL: 5432 * MongoDB: 27017 * Redis: 6379 * SQL Server: 1433 * CouchDB: 5984 * **Risk:** Unrestricted database access can lead to data breaches and unauthorized data access. ### 4. iaas\_security\_group\_all\_traffic\_unrestricted * **Severity:** Critical * **Description:** Detects security groups that allow all traffic from the internet. * **Detection Logic:** * Checks for rules with `port_range=None` (all ports) * Checks for rules with port range covering 0-65535 or 1-65535 * Flags unrestricted IP ranges * Critical security misconfiguration requiring immediate remediation ### Important Implementation Notes **Self-Referencing Security Group Rules:** Security group rules with `remoteSecurityGroupId` set are automatically filtered out from unrestricted access checks. These rules only allow traffic from instances within the same security group (self-referencing), not from the internet, and are therefore not flagged as security risks. **Rule Display Names:** All findings include user-friendly rule descriptions when available. If a security group rule has a description field set (the name shown in the StackIT UI), it will be displayed in the finding message along with the rule ID: * With description: `'Allow SSH from office' (sgr-abc123)` * Without description: `'sgr-abc123'` **Network Interface (NIC) Usage Filtering:** The IaaS service lists project NICs and records the security group IDs attached to them. Checks use that signal to decide whether a security group is in use: 1. **Default behavior:** Report security groups attached to at least one NIC. 2. **`--scan-unused-services`:** Report every security group, including unused ones. 3. **FAIL logic:** Internet exposure is driven by security group rules that allow unrestricted source ranges, not by the presence of a public IP on the NIC. **Unrestricted IP Ranges:** The StackIT API represents "unrestricted" in two ways: * **`ip_range=null`**: No IP restriction specified (implicit unrestricted) * **`ip_range="0.0.0.0/0"` or `"::/0"`**: Explicitly configured to allow all IPs Both are flagged as unrestricted. A `null` value is **more permissive** than an explicit range and applies to all protocols/ports if other fields are also `null`. ## Requirements ### Python Version * **Minimum:** Python 3.10+ * **Reason:** The StackIT SDK requires Python 3.10 or higher ### Dependencies The StackIT provider requires the following Python packages (automatically installed with Prowler): * **stackit-core** (v0.2.0): Core SDK for StackIT API authentication and configuration * **stackit-iaas** (v1.4.0): IaaS service SDK for managing compute resources * **stackit-resourcemanager** (v0.8.0): Resource Manager SDK for fetching project metadata (e.g., project names) These dependencies are defined in `pyproject.toml` and installed automatically with: ```bash theme={null} poetry install ``` **Note:** The `stackit-resourcemanager` package enables automatic retrieval of project names for display in reports. If this package is not available, Prowler will still function normally but project names will be empty in the output. ## Region Support ### Supported Regions * **Available Regions:** `eu01` (Germany South) and `eu02` (Austria West) * **Default:** All scans use both `eu01` and `eu02` regions by default. ### Multi-Region Scanning Prowler supports scanning multiple StackIT regions in a single execution. By default, it will scan all regions defined in the `stackit_regions_by_service.json` configuration file. ### CLI Argument You can specify which regions to scan using the `--stackit-region` argument: ```bash theme={null} # Scan only eu01 prowler stackit --stackit-region eu01 # Scan both eu01 and eu02 prowler stackit --stackit-region eu01 eu02 ``` ### Implementation Details * **Regional Clients:** Prowler generates a separate API client for each audited region. * **Service Iteration:** Each service (e.g., IaaS) iterates through the regional clients to fetch and audit resources. * **Identity Tracking:** The `audited_regions` are stored in the identity model for reporting. ### Future Enhancements As StackIT adds more regions, they can be easily added to Prowler by updating the `prowler/providers/stackit/stackit_regions_by_service.json` file without requiring code changes. ## Command Examples ### Scan Specific Regions Scan only the `eu01` region: ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --stackit-region eu01 ``` Scan multiple regions: ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --stackit-region eu01 eu02 ``` ### Scan Specific Checks Run only SSH unrestricted check: ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --checks iaas_security_group_ssh_unrestricted ``` ### Scan All Security Group Checks ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --services iaas ``` ### Output Formats Generate JSON output: ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --output-formats json ``` Generate HTML report: ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --output-formats html ``` ## Known Limitations ### Current Limitations 1. **Single Project Scope**: Only one project can be scanned at a time 2. **Service Coverage**: Only the IaaS service is currently implemented 3. **Check Coverage**: Limited to security group network security checks (4 checks total) 4. **No Compliance Frameworks**: Compliance framework mappings are not yet implemented ### Planned Enhancements * Multi-project scanning capability * Additional IaaS checks (volume encryption, server public IP exposure, backup status) * Compliance framework mappings (CIS, custom StackIT best practices) * StackIT CLI remediation examples in metadata ## Troubleshooting ### Authentication Errors **Error:** `StackIT service account key was rejected` **Solutions:** 1. Re-issue the service account key in the StackIT Portal 2. Verify the service account key file or inline JSON content is complete 3. Check that the service account has the necessary permissions (`iaas.viewer` or `project.owner`) 4. Ensure the service account key is provided through `STACKIT_SERVICE_ACCOUNT_KEY_PATH`, `STACKIT_SERVICE_ACCOUNT_KEY`, or the matching CLI arguments **Error:** `StackIT credentials not found or are invalid` **Solutions:** 1. Ensure the project ID and one service account credential source are provided 2. Check that credentials are set via environment variables or command-line arguments 3. Verify there are no extra spaces or newlines in the credentials **Error:** `Invalid StackIT project ID format` **Solutions:** 1. Verify the project ID is a valid UUID format: `12345678-1234-1234-1234-123456789abc` 2. Copy the project ID directly from the StackIT Portal 3. Ensure there are no extra spaces or quotes around the UUID ### API Connection Errors **Error:** `Failed to connect to StackIT API` **Solutions:** 1. Check your internet connection 2. Verify the StackIT API endpoint is accessible from your network 3. Check if there are any firewall rules blocking HTTPS connections 4. Review the full error message for specific API error codes **Error:** `HTTP 403 Forbidden` **Solutions:** 1. Verify the service account has the correct permissions 2. Ensure the project ID is correct and you have access to it 3. Check that the service account is enabled (not disabled or expired) 4. Verify the service account key has not been revoked **Error:** `HTTP 404 Not Found` **Solutions:** 1. Verify the project ID exists and is correct 2. Check that the IaaS service is enabled in your project 3. Ensure you're using the correct region (eu01) ### Empty Results **Issue:** No security groups or findings reported **Solutions:** 1. Verify that security groups exist in your project 2. Check that the IaaS service is properly configured 3. Ensure the service account has `iaas.viewer` permission 4. Check Prowler logs for any API errors (use `--log-level DEBUG`) ### Debug Mode Enable debug logging for detailed troubleshooting: ```bash theme={null} export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json" prowler stackit \ --stackit-project-id "your-project-id" \ --log-level DEBUG ``` This will show: * API authentication details (with inline service account keys redacted) * Resource discovery progress * Security rule parsing details * Any API errors or warnings ## Specific Patterns in StackIT Services The generic service pattern is described in [service page](/developer-guide/services#service-structure-and-initialisation). You can find all the currently implemented services in the following locations: * Directly in the code, in location [`prowler/providers/stackit/services/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/stackit/services) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new service is following the [service implementation documentation](/developer-guide/services#adding-a-new-service) and taking other StackIT services as reference. ### StackIT Service Common Patterns * Services communicate with StackIT using the StackIT Python SDK, you can find the documentation [here](https://github.com/stackitcloud/stackit-sdk-python). * Service constructors receive a `StackitProvider` instance and use it to access credentials, identity, and configuration. * The provider builds StackIT SDK `Configuration` objects from the service account key path or inline key content. * Resource containers **must** be initialized in the constructor, typically as lists or dictionaries. * Do not manipulate `os.environ` for credentials inside services. Use the provider session and SDK configuration helpers. * All StackIT resources are represented as Pydantic `BaseModel` classes, providing type safety and structured access to resource attributes. * StackIT SDK calls are wrapped in try/except blocks, with specific handling for API errors, always logging errors. * **Centralized Error Handling**: Use `provider.handle_api_error(exception)` for consistent authentication error detection across all services. * **SDK Warning Suppression**: StackIT SDK prints deprecation warnings to stderr - use the `suppress_stderr()` context manager during SDK initialization and API calls. * **Unrestricted Access Detection**: In StackIT API, `None` values mean "allow all" (more permissive than explicit 0.0.0.0/0). * `protocol=None` → All protocols allowed * `ip_range=None` → All source IPs allowed (unrestricted!) * `port_range=None` → All ports allowed * `remote_security_group_id` set → Only allows traffic from the same security group (not unrestricted!) ### IaaS Service Specific Patterns **Security Group Discovery:** ```python theme={null} # List all security groups security_groups = client.list_security_groups( project_id=self.project_id, region=region, ) # List network interfaces to determine security group usage nics = client.list_project_nics( project_id=self.project_id, region=region, ) # Checks report in-use security groups by default. Use --scan-unused-services # to include security groups that are not attached to any NIC. ``` **Centralized Authentication Error Handling:** ```python theme={null} def _handle_api_call(self, api_function, *args, **kwargs): """Wrapper for API calls with centralized error handling.""" try: with suppress_stderr(): # Suppress SDK warnings return api_function(*args, **kwargs) except Exception as e: # Use centralized error handler from provider self.provider.handle_api_error(e) # Detects 401 and raises StackITInvalidTokenError ``` **Unrestricted Access Detection:** ```python theme={null} def is_unrestricted(rule): """Check if a rule allows unrestricted access.""" # Filter out self-referencing rules if rule.remote_security_group_id is not None: return False # Check for unrestricted IP ranges return rule.ip_range is None or rule.ip_range in ["0.0.0.0/0", "::/0"] def is_tcp(rule): """Check if a rule applies to TCP protocol.""" # None means all protocols (including TCP) return rule.protocol is None or rule.protocol.lower() in ["tcp", "all"] def includes_port(rule, port): """Check if a rule includes a specific port.""" # None means all ports if rule.port_range is None: return True return rule.port_range.min <= port <= rule.port_range.max ``` ## Specific Patterns in StackIT Checks The StackIT checks pattern is described in [checks page](/developer-guide/checks). You can find all the currently implemented checks: * Directly in the code, within each service folder, each check has its own folder named after the name of the check. (e.g. [`prowler/providers/stackit/services/iaas/iaas_security_group_ssh_unrestricted/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/stackit/services/iaas/iaas_security_group_ssh_unrestricted)) * In the [Prowler Hub](https://hub.prowler.com/) for a more human-readable view. The best reference to understand how to implement a new check is following the [check creation documentation](/developer-guide/checks#creating-a-check) and taking other similar StackIT checks as reference. ### Check Report Class The `CheckReportStackIT` class models a single finding for a StackIT resource in a check report. It is defined in [`prowler/lib/check/models.py`](https://github.com/prowler-cloud/prowler/blob/master/prowler/lib/check/models.py) and inherits from the generic `Check_Report` base class. #### Purpose `CheckReportStackIT` extends the base report structure with StackIT-specific fields, enabling detailed tracking of the resource, project, and location associated with each finding. #### Constructor and Attribute Population When you instantiate `CheckReportStackIT`, you must provide the check metadata and a resource object. The class will attempt to automatically populate its StackIT-specific attributes from the resource, using the following logic: * **`resource_id`**: * Uses `resource.id` if present. * Otherwise, uses `resource.resource_id` if present. * Defaults to an empty string if none are available. * **`resource_name`**: * Uses `resource.name` if present. * Defaults to an empty string if not available. * **`project_id`**: * Uses `resource.project_id` if present. * Defaults to an empty string if not available (should be set in check logic). * **`location`**: * Uses `resource.region` if present. * Otherwise, uses `resource.location` if present. * Defaults to an empty string if not available. If the resource object does not contain the required attributes, you must set them manually in the check logic. Other attributes are inherited from the `Check_Report` class, from which you **always** have to set the `status` and `status_extended` attributes in the check logic. #### Example Usage ```python theme={null} from prowler.lib.check.models import CheckReportStackIT report = CheckReportStackIT( metadata=self.metadata(), resource=security_group ) report.status = "FAIL" report.status_extended = f"Security group {security_group.name} allows unrestricted SSH access from the internet." report.resource_id = security_group.id report.resource_name = security_group.name report.project_id = security_group.project_id report.location = security_group.region ``` ### Common Check Pattern ```python theme={null} from prowler.lib.check.models import Check, CheckReportStackIT from prowler.providers.stackit.services.iaas.iaas_client import iaas_client class iaas_security_group_ssh_unrestricted(Check): """Check if IaaS security groups allow unrestricted SSH access.""" def execute(self): findings = [] for security_group in iaas_client.security_groups: if not (iaas_client.scan_unused_services or security_group.in_use): continue report = CheckReportStackIT( metadata=self.metadata(), resource=security_group ) report.status = "PASS" report.status_extended = f"Security group {security_group.name} does not allow unrestricted SSH access." # Check each rule for rule in security_group.rules: if (rule.is_ingress() and rule.is_tcp() and rule.includes_port(22) and rule.is_unrestricted()): report.status = "FAIL" report.status_extended = f"Security group {security_group.name} allows unrestricted SSH access from the internet." break findings.append(report) return findings ``` ## Resources ### Official StackIT Documentation * **StackIT Portal**: [https://portal.stackit.cloud/](https://portal.stackit.cloud/) * **StackIT Documentation**: [https://docs.stackit.cloud/](https://docs.stackit.cloud/) * **StackIT API Documentation**: [https://docs.api.eu01.stackit.cloud/](https://docs.api.eu01.stackit.cloud/) ### Python SDK * **StackIT Python SDK (GitHub)**: [https://github.com/stackitcloud/stackit-sdk-python](https://github.com/stackitcloud/stackit-sdk-python) * **stackit-core (PyPI)**: [https://pypi.org/project/stackit-core/](https://pypi.org/project/stackit-core/) * **stackit-iaas (PyPI)**: [https://pypi.org/project/stackit-iaas/](https://pypi.org/project/stackit-iaas/) * **IaaS Models**: [https://github.com/stackitcloud/stackit-sdk-python/tree/main/services/iaas/src/stackit/iaas/models](https://github.com/stackitcloud/stackit-sdk-python/tree/main/services/iaas/src/stackit/iaas/models) ### Prowler Resources * **Provider Implementation**: [`prowler/providers/stackit/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/stackit/) * **IaaS Service**: [`prowler/providers/stackit/services/iaas/`](https://github.com/prowler-cloud/prowler/tree/master/prowler/providers/stackit/services/iaas/) * **Prowler Hub**: [https://hub.prowler.com/](https://hub.prowler.com/) * **GitHub Issues**: [https://github.com/prowler-cloud/prowler/issues](https://github.com/prowler-cloud/prowler/issues) ## Contributing If you'd like to contribute to the StackIT provider: 1. **Add New Checks**: Follow the [check creation guide](/developer-guide/checks#creating-a-check) and use existing StackIT checks as templates 2. **Enhance Services**: Implement additional IaaS resource discovery or add new services 3. **Improve Documentation**: Add metadata enhancements, CLI remediation examples, or Terraform code samples 4. **Report Issues**: Submit bug reports or feature requests on [GitHub](https://github.com/prowler-cloud/prowler/issues) ### Quick Start for Contributors 1. **Install dependencies**: `poetry install` (includes stackit-core and stackit-iaas) 2. **Set credentials**: Export `STACKIT_SERVICE_ACCOUNT_KEY_PATH` and `STACKIT_PROJECT_ID` 3. **Run checks**: `prowler stackit` 4. **View code**: Start in `prowler/providers/stackit/` 5. **Add checks**: Create new check directories under `services/iaas/` 6. **Run tests**: `poetry run pytest tests/providers/stackit/ -v` ### Code Quality Standards The StackIT provider should follow the same quality expectations as the rest of the Prowler SDK: * Keep service and check logic covered by unit tests. * Redact inline service account keys from generated output. * Keep documentation aligned with the implemented services and checks. * Follow existing provider, service, and check patterns before adding StackIT-specific abstractions. # Unit Tests for Prowler Checks Source: https://docs.prowler.com/developer-guide/unit-testing Unit tests for Prowler checks vary based on the provider being evaluated. Below are key resources and insights gained throughout the testing process. **Python Testing** * [https://docs.python-guide.org/writing/tests/](https://docs.python-guide.org/writing/tests/) **Where to Patch** * [https://docs.python.org/3/library/unittest.mock.html#where-to-patch](https://docs.python.org/3/library/unittest.mock.html#where-to-patch) * [https://stackoverflow.com/questions/893333/multiple-variables-in-a-with-statement](https://stackoverflow.com/questions/893333/multiple-variables-in-a-with-statement) * ​[https://docs.python.org/3/reference/compound\_stmts.html#the-with-statement](https://docs.python.org/3/reference/compound_stmts.html#the-with-statement) **Utilities for Tracing Mocking and Test Execution** * [https://news.ycombinator.com/item?id=36054868](https://news.ycombinator.com/item?id=36054868) * [https://docs.python.org/3/library/sys.html#sys.settrace](https://docs.python.org/3/library/sys.html#sys.settrace) * [https://github.com/kunalb/panopticon](https://github.com/kunalb/panopticon) ## General Recommendations When writing tests for Prowler provider checks, follow these guidelines to maximize coverage across test scenarios: 1. Zero Findings Scenario: Develop tests where no resources exist. Prowler returns zero findings if the audited service lacks the required resources. 2. Positive and Negative Outcomes: Create tests that generate both a passing (`PASS`) and a failing (`FAIL`) result. 3. Multi-Resource Evaluations: Design tests with multiple resources to verify check behavior and ensure the correct number of findings. ## Test File Naming Conventions Test files follow the pattern `{service}_{check_name}_test.py` for checks and `{service}_service_test.py` for services. ### Duplicate Names Across Providers When a test file name already exists in another provider, add your provider prefix to avoid conflicts. A GitHub Action will fail if duplicate names are detected. **Example:** If `kms_service_test.py` already exists in AWS, name your Oracle Cloud test `oraclecloud_kms_service_test.py`. ## Running Prowler Tests To execute the Prowler test suite, install the necessary dependencies listed in the `pyproject.toml` file. ### Prerequisites If you have not installed Prowler yet, refer to the [developer guide introduction](/developer-guide/introduction#getting-the-code-and-installing-all-dependencies). ### Executing Tests Navigate to the project's root directory and execute: `pytest -n auto -vvv -s -x` Alternatively, use: `Makefile` with `make test`. Other Commands for Running Tests * Running tests for a provider: `pytest -n auto -vvv -s -x tests/providers//services` * Running tests for a provider service: `pytest -n auto -vvv -s -x tests/providers//services/` * Running tests for a provider check: `pytest -n auto -vvv -s -x tests/providers//services//` > [!NOTE] > > Refer to the [pytest documentation](https://docs.pytest.org/en/7.1.x/getting-started.html) for more details. ## AWS Service Dependency Table (CI Optimization) To optimize CI pipeline execution time, the GitHub Actions workflow for AWS tests uses a **service dependency table** that determines which tests to run based on changed files. This ensures that when a service is modified, all dependent services are also tested. ### How It Works The dependency table is defined in `.github/workflows/sdk-tests.yml` within the "Resolve AWS services under test" step. When files in a specific AWS service are changed: 1. Tests for the changed service are run 2. Tests for all services that **depend on** the changed service are also run For example, if you modify the `ec2` service, tests will also run for `dlm`, `dms`, `elbv2`, `emr`, `inspector2`, `rds`, `redshift`, `route53`, `shield`, `ssm`, and `workspaces` because these services use the EC2 client. ### Current Dependency Table The table maps a service (key) to the list of services that depend on it (values): | Service | Dependent Services | | - | - | | `acm` | `elb` | | `autoscaling` | `dynamodb` | | `awslambda` | `ec2`, `inspector2` | | `backup` | `dynamodb`, `ec2`, `rds` | | `bedrockagentcore` | `cloudtrail` | | `cloudfront` | `shield` | | `cloudtrail` | `awslambda`, `cloudwatch` | | `cloudwatch` | `bedrock` | | `ec2` | `dlm`, `dms`, `elbv2`, `emr`, `inspector2`, `rds`, `redshift`, `route53`, `shield`, `ssm` | | `ecr` | `inspector2` | | `elb` | `shield` | | `elbv2` | `shield` | | `globalaccelerator` | `shield` | | `iam` | `bedrock`, `bedrockagentcore`, `cloudtrail`, `cloudwatch`, `codebuild` | | `kafka` | `firehose` | | `kinesis` | `firehose` | | `kms` | `kafka` | | `organizations` | `iam`, `servicecatalog` | | `route53` | `shield` | | `s3` | `bedrock`, `cloudfront`, `cloudtrail`, `macie` | | `ssm` | `ec2` | | `vpc` | `awslambda`, `ec2`, `efs`, `elasticache`, `neptune`, `networkfirewall`, `rds`, `redshift`, `workspaces` | | `waf` | `elbv2` | | `wafv2` | `cognito`, `elbv2` | ### When to Update the Table You must update the dependency table when: 1. **A new check or service uses another service's client**: If your check imports a client from another service (e.g., `from prowler.providers.aws.services.ec2.ec2_client import ec2_client` in a non-ec2 check), add your service to the dependent services list of that client's service. 2. **A service relationship changes**: If you remove or add a service client dependency in an existing check, update the table accordingly. ### How to Update the Table 1. Open `.github/workflows/sdk-tests.yml` 2. Find the `dependents` dictionary in the "Resolve AWS services under test" step 3. Add or modify entries as needed 4. **Update this documentation page** (`docs/developer-guide/unit-testing.mdx`) to reflect the changes in the [Current Dependency Table](#current-dependency-table) section above ```python theme={null} dependents = { # ... existing entries ... "service_being_used": ["service_that_uses_it"], } ``` **Example**: If you create a new check in the `newservice` service that imports `ec2_client`, add `newservice` to the `ec2` entry: ```python theme={null} "ec2": ["dlm", "dms", "elbv2", "emr", "inspector2", "newservice", "rds", "redshift", "route53", "shield", "ssm"], ``` > [!WARNING] > > Failing to update this table when adding cross-service dependencies may result in CI tests passing even when related functionality is broken, as the dependent service tests won't be triggered. ## AWS Testing Approaches For AWS provider, different testing approaches apply based on API coverage based on several criteria. > [!NOTE] > > Prowler leverages and contributes to the [Moto](https://github.com/getmoto/moto) library for mocking AWS infrastructure in tests. * AWS API Calls Covered by [Moto](https://github.com/getmoto/moto): * Service Tests: `@mock_aws` * Checks Tests: `@mock_aws` * AWS API Calls Not Covered by Moto: * Service Tests: `mock_make_api_call` * Checks Tests: [MagicMock](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock) * AWS API Calls Partially Covered by Moto: * Service Tests: `@mock_aws` and `mock_make_api_call` * Check Tests: `@mock_aws` and `mock_make_api_call` #### AWS Check Testing Scenarios The following section provides examples for each testing scenario. The primary distinction between these scenarios depends on whether the [Moto](https://github.com/getmoto/moto) library covers the AWS API calls made by the service. You can review the supported API calls [here](https://github.com/getmoto/moto/blob/master/IMPLEMENTATION_COVERAGE.md). ### AWS Check Testing Approach For AWS test examples, we reference tests for the `iam_password_policy_uppercase` check. This section is categorized based on [Moto](https://github.com/getmoto/moto) API coverage. #### API Calls Covered by Moto When the [Moto](https://github.com/getmoto/moto) library supports the API calls required for testing, use the `@mock_aws` decorator. This ensures that all AWS API calls within the decorated function are properly mocked while maintaining state within the test. ```python theme={null} # Import unittest.mock to enable object patching # This prevents shared objects between tests, ensuring test isolation from unittest import mock # Import Boto3 client and session for AWS API calls from boto3 import client, session # Import Moto decorator for mocking AWS services from moto import mock_aws # Define constants for test execution AWS_ACCOUNT_NUMBER = "123456789012" AWS_REGION = "us-east-1" # Test class naming convention: Test_ class Test_iam_password_policy_uppercase: # Apply the Moto decorator for AWS service mocking @mock_aws # Test naming convention: test___ def test_iam_password_policy_no_uppercase_flag(self): Steps # Step 1: Create an IAM client for API calls in the specified region iam_client = client("iam", region_name=AWS_REGION) # Step 2: Modify the account password policy to disable uppercase character enforcement # Action: Setting RequireUppercaseCharacters to False iam_client.update_account_password_policy(RequireUppercaseCharacters=False) # Step 3: Mock the AWS provider to ensure isolated testing # Using 'set_mocked_aws_provider' allows overriding the provider response # This mocked provider is defined in test fixtures aws_provider = set_mocked_aws_provider([AWS_REGION_US_EAST_1]) # Step 4: Ensure Prowler service imports occur within the decorated function # This prevents accidental real API calls to AWS during test execution from prowler.providers.aws.services.iam.iam_service import IAM # Mocking AWS Provider and IAM Client for Prowler Tests #Prowler for AWS relies on a shared object, aws_provider, which stores provider-related information. # To ensure proper test isolation and prevent shared objects between tests, we apply mocking techniques. # Mocking Global AWS Provider #To mock the global provider, we use mock.patch() to override the get_global_provider() method, ensuring aws_provider is the return value. with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", return_value=aws_provider, ), # Mocking IAM Client for Test Isolation #In addition to mocking the provider, we must also mock the iam_client from the check. This ensures that the IAM client used in the test is the one explicitly created within the test. # ⚠️ Important: # patch != import—simply importing does not ensure proper isolation. # Running tests in parallel may cause unintended object initialization, impacting test integrity. with mock.patch( "prowler.providers.aws.services.iam.iam_password_policy_uppercase.iam_password_policy_uppercase.iam_client", new=IAM(aws_provider), ): # Importing the IAM Check # To prevent initialization issues, import the check inside the two-mock context. # This ensures the IAM client does not retain shared data from aws_provider or the IAM service. from prowler.providers.aws.services.iam.iam_password_policy_uppercase.iam_password_policy_uppercase import ( iam_password_policy_uppercase, ) # Executing the IAM Check # Once imported, instantiate the check’s class. check = iam_password_policy_uppercase() # Then run the execute function() # against the set up IAM client. result = check.execute() # Validating the Check Results # Finally, assert all fields to verify expected results. assert len(results) == 1 assert result[0].status == "FAIL" assert result[0].status_extended == "IAM password policy does not srequire at least one uppercase letter." assert result[0].resource_arn == f"arn:aws:iam::{AWS_ACCOUNT_NUMBER}:root" assert result[0].resource_id == AWS_ACCOUNT_NUMBER assert result[0].resource_tags == [] assert result[0].region == AWS_REGION ``` #### Handling API Calls Not Covered by Moto If the IAM service required for testing is not supported by the Moto library, use [MagicMock](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock) to inject objects into the service client. > [!WARNING] > > As stated above, direct service instantiation must be avoided to prevent actual AWS API calls. > [!NOTE] > > The example below demonstrates the IAM GetAccountPasswordPolicy API, which is covered by Moto, but is used for instructional purposes only. #### Mocking Service Objects Using MagicMock The following code demonstrates how to use MagicMock to create service objects. ```python theme={null} # Import unittest.mock to enable object patching # This prevents shared objects between tests, ensuring test isolation from unittest import mock # Define constants for test execution AWS_ACCOUNT_NUMBER = "123456789012" AWS_REGION = "us-east-1" # Test class naming convention: Test_ class Test_iam_password_policy_uppercase: # Test naming convention: test___ def test_iam_password_policy_no_uppercase_flag(self): # Mock IAM client with MagicMock mocked_iam_client = mock.MagicMock # Import IAM PasswordPolicy model, as it has its own model from prowler.providers.aws.services.iam.iam_service import PasswordPolicy # Create a mock PasswordPolicy object with predefined attributes mocked_iam_client.password_policy = PasswordPolicy( length=5, symbols=True, numbers=True, # The value must be set to False to trigger a failure scenario uppercase=False, lowercase=True, allow_change=False, expiration=True, ) # In this scenario, both the IAM service and the iam_client from the check must be mocked to ensure test isolation. This guarantees that the iam_client used in the test is the one explicitly instantiated within the test itself. # Note: Simply applying a patch does not modify imports (patch != import). # If tests are executed in parallel, objects may already be initialized, # leading to unintended shared state and breaking test isolation. # Unlike other cases, we do not use the Moto decorator here. # Instead, we mock the IAM client for both objects to prevent real AWS API interactions. with mock.patch( "prowler.providers.aws.services.iam.iam_service.IAM", new=mocked_iam_client, ), mock.patch( "prowler.providers.aws.services.iam.iam_client.iam_client", new=mocked_iam_client, ): # Importing the IAM Check # To prevent initialization issues, import the check inside the two-mock context. # This ensures the IAM client does not retain shared data from aws_provider or the IAM service. from prowler.providers.aws.services.iam.iam_password_policy_uppercase.iam_password_policy_uppercase import ( iam_password_policy_uppercase, ) # Executing the IAM Check # Once imported, instantiate the check’s class. check = iam_password_policy_uppercase() # Then run the execute function() # against the set up IAM client. result = check.execute() # Validating the Check Results # Finally, assert all fields to verify expected results. assert len(results) == 1 assert result[0].status == "FAIL" assert result[0].status_extended == "IAM password policy does not require at least one uppercase letter." assert result[0].resource_arn == f"arn:aws:iam::{AWS_ACCOUNT_NUMBER}:root" assert result[0].resource_id == AWS_ACCOUNT_NUMBER assert result[0].resource_tags == [] assert result[0].region == AWS_REGION ``` #### Ensuring Test Isolation with Mocked/Patched Objects In all above scenarios, check execution must occur within the context of mocked or patched objects. This guarantees that the test only evaluates objects explicitly created within its scope, preventing interference from shared state or external dependencies. #### Handling Partially Covered API Calls When a service requires API calls that are partially covered by the Moto decorator, additional mocking is necessary. In such cases, custom mocked API calls must be implemented alongside Moto to ensure full coverage. To achieve this, mock the `botocore.client.BaseClient._make_api_call` function—the method responsible for making actual API requests to AWS—using [`mock.patch`](https://docs.python.org/3/library/unittest.mock.html#patch): ```python theme={null} import boto3 import botocore from unittest.mock import patch from moto import mock_aws # Original botocore _make_api_call function orig = botocore.client.BaseClient._make_api_call # Mocked botocore _make_api_call function def mock_make_api_call(self, operation_name, kwarg): # The 'operation_name' follows the snake_case format (get_account_password_policy), # but we use the PascalCase form (GetAccountPasswordPolicy) for consistency with Boto3 conventions. # Reference: https://github.com/boto/botocore/blob/develop/botocore/client.py#L810:L816 if operation_name == 'GetAccountPasswordPolicy': return { 'PasswordPolicy': { 'MinimumPasswordLength': 123, 'RequireSymbols': True|False, 'RequireNumbers': True|False, 'RequireUppercaseCharacters': True|False, 'RequireLowercaseCharacters': True|False, 'AllowUsersToChangePassword': True|False, 'ExpirePasswords': True|False, 'MaxPasswordAge': 123, 'PasswordReusePrevention': 123, 'HardExpiry': True|False } } # If API call patching is not required, return the original method execution. return orig(self, operation_name, kwarg) # Test class naming convention: Test_ class Test_iam_password_policy_uppercase: # Apply custom API call mock decorator for the required service @patch("botocore.client.BaseClient._make_api_call", new=mock_make_api_call) # Also include IAM Moto decorator for supported API calls @mock_iam # Test naming convention: test___ def test_iam_password_policy_no_uppercase_flag(self): # Refer to the previous section for the check test, as the implementation remains unchanged. ``` > [!NOTE] > > This example does not use Moto to simplify the setup. > However, if additional `moto` decorators are applied alongside the patch, Moto will automatically intercept the call to `orig(self, operation_name, kwarg)`. > [!NOTE] > > The source of the above implementation can be found here: [Patch Other Services with Moto](https://docs.getmoto.org/en/latest/docs/services/patching_other_services.html) #### Mocking Several Services Since the provider is being mocked, multiple attributes can be configured to customize its behavior: ```python theme={null} def set_mocked_aws_provider( audited_regions: list[str] = [], audited_account: str = AWS_ACCOUNT_NUMBER, audited_account_arn: str = AWS_ACCOUNT_ARN, audited_partition: str = AWS_COMMERCIAL_PARTITION, expected_checks: list[str] = [], profile_region: str = None, audit_config: dict = {}, fixer_config: dict = {}, scan_unused_services: bool = True, audit_session: session.Session = session.Session( profile_name=None, botocore_session=None, ), original_session: session.Session = None, enabled_regions: set = None, arguments: Namespace = Namespace(), create_default_organization: bool = True, ) -> AwsProvider: ``` If a test is designed for a check that interacts with multiple provider services, each service used must be individually mocked. For instance, if the check `cloudtrail_logs_s3_bucket_access_logging_enabled` relies on both the CloudTrail and S3 clients, the test's service mocking section should be structured as follows: ```python theme={null} with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", return_value=set_mocked_aws_provider( [AWS_REGION_US_EAST_1, AWS_REGION_EU_WEST_1] ), ), mock.patch( "prowler.providers.aws.services.cloudtrail.cloudtrail_logs_s3_bucket_access_logging_enabled.cloudtrail_logs_s3_bucket_access_logging_enabled.cloudtrail_client", new=Cloudtrail( set_mocked_aws_provider([AWS_REGION_US_EAST_1, AWS_REGION_EU_WEST_1]) ), ), mock.patch( "prowler.providers.aws.services.cloudtrail.cloudtrail_logs_s3_bucket_access_logging_enabled.cloudtrail_logs_s3_bucket_access_logging_enabled.s3_client", new=S3( set_mocked_aws_provider([AWS_REGION_US_EAST_1, AWS_REGION_EU_WEST_1]) ), ): ``` As demonstrated in the code above, mocking both the AWS audit information and all used services is mandatory for proper test execution. #### Patching vs. Importing Properly understanding patching versus importing is critical for unit testing with Prowler checks. Given the dynamic nature of the check-loading mechanism, the process for importing a service client within a check follows this structured approach: 1. `.py`: ```python theme={null} from prowler.providers..services.._client import _client ``` 2. `_client.py`: ```python theme={null} from prowler.providers.common.provider import Provider from prowler.providers..services.._service import _client = (Provider.get_global_provider()) ``` Due to the import path structure, patching certain objects does not always ensure full isolation. If multiple tests—executed sequentially or in parallel—reuse service clients, some instances may already be initialized by another check. This can lead to unintended shared state, affecting test accuracy: * `_client` imported at `.py` * `_client` initialised at `_client.py` * `` imported at `_client.py` #### Additional Resources on Mocking Imports For a deeper understanding of mocking imports in Python, refer to the following article: [https://stackoverflow.com/questions/8658043/how-to-mock-an-import](https://stackoverflow.com/questions/8658043/how-to-mock-an-import) #### Approaches to Mocking a Service Client 1\. Mocking the Service Client at the Service Client Level 2\. Mocking a Service Client via Below Code Implementation Once all required attributes are configured for the mocked provider, it can be used as the service client for test execution: ```python title="Mocking the service_client" theme={null} with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", new=set_mocked_aws_provider([]), ), mock.patch( "prowler.providers..services...._client", new=(set_mocked_aws_provider([])), ): ``` will cause that the service will be initialised twice: 1. When `(set_mocked_aws_provider([]))` is mocked out using `mock.patch`, it must be properly prepared before patching to ensure test consistency. 2. At the point of patching, in `_client.py`, and since `mock.patch` needs to access said object and initialise it, `(set_mocked_aws_provider([]))` will be called again. Later, when importing `_client.py` at `.py`, Python uses the mocked instance since the patch was applied at the correct reference point. In the [next section](/developer-guide/unit-testing#mocking-the-service-and-the-service-client-at-the-service-client-level) we will explore an improved approach to mock objects. ##### Mocking the Service and the Service Client at the Service Client Level ##### Mocking a Service Client via Below Code Implementation ```python title="Mocking the service and the service_client" theme={null} with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", new=set_mocked_aws_provider([]), ), mock.patch( "prowler.providers..services..", new=(set_mocked_aws_provider([])), ) as service_client, mock.patch( "prowler.providers..services.._client._client", new=service_client, ): ``` will cause that the service is initialized only once—at the moment of mocking out `set_mocked_aws_provider([])` using `mock.patch`. Later, when Python attempts to import the client at the check level, the execution continues using `from prowler.providers..services.._client`. As a result of it being already mocked out, the execution will continue using `service_client` without getting into `_client.py`. ### Testing AWS Services AWS service testing follows the same methodology as AWS checks: Verify whether the AWS API calls made by the service are covered by Moto. Execute tests on the service `__init__` to ensure correct information retrieval. While service tests resemble *Integration Tests*, as they assess how the service interacts with the provider, they ultimately fall under *Unit Tests*, due to the use of Moto or custom mock objects. For detailed guidance on test creation and existing service tests, check the current [AWS checks implementation](https://github.com/prowler-cloud/prowler/tree/master/tests/providers/aws/services). ## GCP ### GCP Check Testing Approach Currently the GCP Provider does not have a dedicated library for mocking API calls. To ensure proper test isolation, objects must be manually injected into the service client using [MagicMock](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock). Mocking Service Objects Using MagicMock The following code demonstrates how to use MagicMock to create service objects for a GCP check test. This is a real-world implementation, adapted for instructional clarity. ```python theme={null} from re import search from unittest import mock # Import constant values needed in every check from tests.providers.gcp.gcp_fixtures import GCP_PROJECT_ID, set_mocked_gcp_provider # Create a test for the compute_project_os_login_enabled check class Test_compute_project_os_login_enabled: def test_one_compliant_project(self): # Import the service resource model to create the mocked object from prowler.providers.gcp.services.compute.compute_service import Project # Create the custom Project object to be tested project = Project( id=GCP_PROJECT_ID, enable_oslogin=True, ) # Mock IAM client with MagicMock compute_client = mock.MagicMock compute_client.project_ids = [GCP_PROJECT_ID] compute_client.projects = [project] # In this scenario, the app_client from the check must be mocked to ensure that the compute_client used in the test is the explicitly created instance. # Additionally, the return value of the get_global_provider function is mocked to return the predefined GCP mocked provider from the test fixtures. with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", return_value=set_mocked_gcp_provider(), ), mock.patch( "prowler.providers.gcp.services.compute.compute_project_os_login_enabled.compute_project_os_login_enabled.compute_client", new=compute_client, ): # Import the check within the two mocks from prowler.providers.gcp.services.compute.compute_project_os_login_enabled.compute_project_os_login_enabled import ( compute_project_os_login_enabled, ) # Executing the IAM Check # Once imported, instantiate the check’s class. check = compute_project_os_login_enabled() # Then run the execute function() # against the set up Compute client. result = check.execute() # Assert the expected results assert len(result) == 1 assert result[0].status == "PASS" assert search( f"Project {project.id} has OS Login enabled", result[0].status_extended, ) assert result[0].resource_id == project.id assert result[0].location == "global" assert result[0].project_id == GCP_PROJECT_ID # Complementary Test # The following is an additional test for a wider scenario coverage def test_one_non_compliant_project(self): from prowler.providers.gcp.services.compute.compute_service import Project project = Project( id=GCP_PROJECT_ID, enable_oslogin=False, ) compute_client = mock.MagicMock compute_client.project_ids = [GCP_PROJECT_ID] compute_client.projects = [project] with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", return_value=set_mocked_gcp_provider(), ), mock.patch( "prowler.providers.gcp.services.compute.compute_project_os_login_enabled.compute_project_os_login_enabled.compute_client", new=compute_client, ): from prowler.providers.gcp.services.compute.compute_project_os_login_enabled.compute_project_os_login_enabled import ( compute_project_os_login_enabled, ) check = compute_project_os_login_enabled() result = check.execute() assert len(result) == 1 assert result[0].status == "FAIL" assert search( f"Project {project.id} does not have OS Login enabled", result[0].status_extended, ) assert result[0].resource_id == project.id assert result[0].location == "global" assert result[0].project_id == GCP_PROJECT_ID ``` ### Testing GCP Services The testing of Google Cloud Services follows the same principles as the one of Google Cloud checks. While all API calls must be mocked, attribute setup for API calls in this scenario is defined in the fixtures file, specifically within the [fixtures file](https://github.com/prowler-cloud/prowler/blob/master/tests/providers/gcp/gcp_fixtures.py) in the `mock_api_client` function. > [!WARNING] > > Every method within a service must be tested to ensure full coverage and accurate validation. The following example presents a real testing class, but includes additional comments for educational purposes, explaining key concepts and implementation details. ```python title="BigQuery Service Test" theme={null} # Import unittest.mock.patch to enable object patching # This prevents shared objects between tests, ensuring test isolation from unittest.mock import patch # Import the class needed from the service file from prowler.providers.gcp.services.bigquery.bigquery_service import BigQuery # Use necessary constants and functions from fixtures file from tests.providers.gcp.gcp_fixtures import ( GCP_PROJECT_ID, mock_api_client, mock_is_api_active, set_mocked_gcp_provider, ) class TestBigQueryService: # The only method needed to test full service def test_service(self): # Mocking '__is_api_active__' ensures that the test utilizes the predefined mocked project instead of a real instance. # Additionally, all client interactions are patched to use the mocked API calls. with patch( "prowler.providers.gcp.lib.service.service.GCPService.__is_api_active__", new=mock_is_api_active, ), patch( "prowler.providers.gcp.lib.service.service.GCPService.__generate_client__", new=mock_api_client, ): # Instantiate an object of class with the mocked provider bigquery_client = BigQuery( set_mocked_gcp_provider(project_ids=[GCP_PROJECT_ID]) ) # Verify that all attributes of the tested class are correctly initialized based on the API calls mocked from the GCP fixture file. assert bigquery_client.service == "bigquery" assert bigquery_client.project_ids == [GCP_PROJECT_ID] assert len(bigquery_client.datasets) == 2 assert bigquery_client.datasets[0].name == "unique_dataset1_name" assert bigquery_client.datasets[0].id.__class__.__name__ == "str" assert bigquery_client.datasets[0].region == "US" assert bigquery_client.datasets[0].cmk_encryption assert bigquery_client.datasets[0].public assert bigquery_client.datasets[0].project_id == GCP_PROJECT_ID assert bigquery_client.datasets[1].name == "unique_dataset2_name" assert bigquery_client.datasets[1].id.__class__.__name__ == "str" assert bigquery_client.datasets[1].region == "EU" assert not bigquery_client.datasets[1].cmk_encryption assert not bigquery_client.datasets[1].public assert bigquery_client.datasets[1].project_id == GCP_PROJECT_ID assert len(bigquery_client.tables) == 2 assert bigquery_client.tables[0].name == "unique_table1_name" assert bigquery_client.tables[0].id.__class__.__name__ == "str" assert bigquery_client.tables[0].region == "US" assert bigquery_client.tables[0].cmk_encryption assert bigquery_client.tables[0].project_id == GCP_PROJECT_ID assert bigquery_client.tables[1].name == "unique_table2_name" assert bigquery_client.tables[1].id.__class__.__name__ == "str" assert bigquery_client.tables[1].region == "US" assert not bigquery_client.tables[1].cmk_encryption assert bigquery_client.tables[1].project_id == GCP_PROJECT_ID ``` Clarifying Value Origins with an Example Understanding where specific values originate can be challenging, so the following example provides clarity. * Step 1: Identify the API Call for Dataset Retrieval To determine how datasets are obtained, examine the API call used by the service. In this case, the relevant service call is: `self.client.datasets().list(projectId=project_id)`. * Step 2: Mocking the API Call in the Fixture File In the fixture file, mock this call in the `MagicMock` client, in the function `mock_api_client`. * Step 3: Structuring the Mock Function The best approach for mocking is to adhere to the service’s existing format: Define a dedicated function that modifies the client. Follow the naming convention: `mock_api__calls` (*endpoint* refers to the first attribute pointed after *client*). For BigQuery, the mock function is called `mock_api_dataset_calls`. Within this function, an assignment is made for use in the `_get_datasets` method of the BigQuery class: ```python theme={null} # Mocking datasets dataset1_id = str(uuid4()) dataset2_id = str(uuid4()) client.datasets().list().execute.return_value = { "datasets": [ { "datasetReference": { "datasetId": "unique_dataset1_name", "projectId": GCP_PROJECT_ID, }, "id": dataset1_id, "location": "US", }, { "datasetReference": { "datasetId": "unique_dataset2_name", "projectId": GCP_PROJECT_ID, }, "id": dataset2_id, "location": "EU", }, ] } ``` ## Azure ### Azure Check Testing Approach Currently the Azure Provider does not have a dedicated library for mocking API calls. To ensure proper test isolation, objects must be manually injected into the service client using [MagicMock](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock). Mocking Service Objects Using MagicMock The following code demonstrates how to use MagicMock to create service objects for an Azure check test. This is a real-world implementation, adapted for instructional clarity. ```python title="app_ensure_http_is_redirected_to_https_test.py" theme={null} # Import unittest.mock to enable object patching # This prevents shared objects between tests, ensuring test isolation from unittest import mock from uuid import uuid4 # Import some constans values needed in almost every check from tests.providers.azure.azure_fixtures import ( AZURE_SUBSCRIPTION_ID, set_mocked_azure_provider, ) # Create a test for the app_ensure_http_is_redirected_to_https check class Test_app_ensure_http_is_redirected_to_https: # Test naming convention: test___ def test_app_http_to_https_disabled(self): resource_id = f"/subscriptions/{uuid4()}" # Mock IAM client with MagicMock app_client = mock.MagicMock # In this scenario, the app_client from the check must be mocked to ensure that the app_client used in the test is the explicitly created instance. # Additionally, the return value of the get_global_provider function is mocked to return the predefined Azure mocked provider from the test fixtures. with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", return_value=set_mocked_azure_provider(), ), mock.patch( "prowler.providers.azure.services.app.app_ensure_http_is_redirected_to_https.app_ensure_http_is_redirected_to_https.app_client", new=app_client, ): # Import the check within the two mocks from prowler.providers.azure.services.app.app_ensure_http_is_redirected_to_https.app_ensure_http_is_redirected_to_https import ( app_ensure_http_is_redirected_to_https, ) # Import the service resource model to create the mocked object from prowler.providers.azure.services.app.app_service import WebApp # Create the custom App object to be tested app_client.apps = { AZURE_SUBSCRIPTION_ID: { resource_id: WebApp( resource_id=resource_id, name="app_id-1", auth_enabled=True, configurations=mock.MagicMock(), client_cert_mode="Ignore", https_only=False, identity=None, location="West Europe", ) } } # Executing the IAM Check # Once imported, instantiate the check’s class. check = app_ensure_http_is_redirected_to_https() # Then run the execute function() # against the set up App client. result = check.execute() # Assert the expected results assert len(result) == 1 assert result[0].status == "FAIL" assert ( result[0].status_extended == f"HTTP is not redirected to HTTPS for app 'app_id-1' in subscription '{AZURE_SUBSCRIPTION_ID}'." ) assert result[0].resource_name == "app_id-1" assert result[0].resource_id == resource_id assert result[0].subscription == AZURE_SUBSCRIPTION_ID assert result[0].location == "West Europe" # Complementary Test # The following is an additional test for a wider scenario coverage def test_app_http_to_https_enabled(self): resource_id = f"/subscriptions/{uuid4()}" app_client = mock.MagicMock with mock.patch( "prowler.providers.common.provider.Provider.get_global_provider", return_value=set_mocked_azure_provider(), ), mock.patch( "prowler.providers.azure.services.app.app_ensure_http_is_redirected_to_https.app_ensure_http_is_redirected_to_https.app_client", new=app_client, ): from prowler.providers.azure.services.app.app_ensure_http_is_redirected_to_https.app_ensure_http_is_redirected_to_https import ( app_ensure_http_is_redirected_to_https, ) from prowler.providers.azure.services.app.app_service import WebApp app_client.apps = { AZURE_SUBSCRIPTION_ID: { resource_id: WebApp( resource_id=resource_id, name="app_id-1", auth_enabled=True, configurations=mock.MagicMock(), client_cert_mode="Ignore", https_only=True, identity=None, location="West Europe", ) } } check = app_ensure_http_is_redirected_to_https() result = check.execute() assert len(result) == 1 assert result[0].status == "PASS" assert ( result[0].status_extended == f"HTTP is redirected to HTTPS for app 'app_id-1' in subscription '{AZURE_SUBSCRIPTION_ID}'." ) assert result[0].resource_name == "app_id-1" assert result[0].resource_id == resource_id assert result[0].subscription == AZURE_SUBSCRIPTION_ID assert result[0].location == "West Europe" ``` ### Testing Azure Services The testing of Azure Services follows the same principles as the one of Google Cloud checks. All API calls are still mocked, but for methods that initialize attributes via an API call, use the [patch](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch) decorator at the beginning of the class to ensure proper mocking. > [!WARNING] > > **Remember** > > Every method within a service must be tested to ensure full coverage and accurate validation. The following example presents a real testing class, but includes additional comments for educational purposes, explaining key concepts and implementation details. ```python title="AppInsights Service Test" theme={null} # Import unittest.mock.patch to enable object patching # This prevents shared objects between tests, ensuring test isolation from unittest.mock import patch # Import the models needed from the service file from prowler.providers.azure.services.appinsights.appinsights_service import ( AppInsights, Component, ) # Import some constans values needed in almost every check from tests.providers.azure.azure_fixtures import ( AZURE_SUBSCRIPTION_ID, set_mocked_azure_provider, ) # Function to mock the service function _get_components; the aim of this function is to return a possible value that a real function could return. def mock_appinsights_get_components(_): return { AZURE_SUBSCRIPTION_ID: { "app_id-1": Component( resource_id="/subscriptions/resource_id", resource_name="AppInsightsTest", location="westeurope", ) } } # Patch decorator to use the mocked function instead of the function with the real API call @patch( "prowler.providers.azure.services.appinsights.appinsights_service.AppInsights._get_components", new=mock_appinsights_get_components, ) class Test_AppInsights_Service: # Mandatory test for every service; this method tests if the instance of the client is correct. def test_get_client(self): app_insights = AppInsights(set_mocked_azure_provider()) assert ( app_insights.clients[AZURE_SUBSCRIPTION_ID].__class__.__name__ == "ApplicationInsightsManagementClient" ) # Second typical method that tests if subscriptions are defined inside the client object. def test__get_subscriptions__(self): app_insights = AppInsights(set_mocked_azure_provider()) assert app_insights.subscriptions.__class__.__name__ == "dict" # Test for the function _get_components; the mocked function is used within this client. def test_get_components(self): appinsights = AppInsights(set_mocked_azure_provider()) assert len(appinsights.components) == 1 assert ( appinsights.components[AZURE_SUBSCRIPTION_ID]["app_id-1"].resource_id == "/subscriptions/resource_id" ) assert ( appinsights.components[AZURE_SUBSCRIPTION_ID]["app_id-1"].resource_name == "AppInsightsTest" ) assert ( appinsights.components[AZURE_SUBSCRIPTION_ID]["app_id-1"].location == "westeurope" ) ``` # Basic Usage Source: https://docs.prowler.com/getting-started/basic-usage/prowler-app ## Access Prowler Local Server After [installation](/getting-started/installation/prowler-app), navigate to [http://localhost:3000](http://localhost:3000) and sign up with email and password. ![Sign Up Button](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/images/sign-up-button.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=d5f1ba7c5275fe482031ed83795f3484) ![Sign Up](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/images/sign-up.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=3be9d985875b343f29b8c985173531ce) > [!NOTE] > > **User creation and default tenant behavior** > > When creating a new user, the behavior depends on whether an invitation is provided: > > * **Without an invitation**: > > * A new tenant is automatically created. > * The new user is assigned to this tenant. > * A set of **RBAC admin permissions** is generated and assigned to the user for the newly-created tenant. > * **With an invitation**: The user is added to the specified tenant with the permissions defined in the invitation. > > This mechanism ensures that the first user in a newly created tenant has administrative permissions within that tenant. ## Log In Access Prowler Local Server by logging in with **email and password**. ![Log In](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/log-in.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=f9f46846bdbb876aad6c8e67ecd02aa9) ## Add Provider Configure a provider for scanning: 1. Navigate to `Settings > Providers` and click `Add Provider`. 2. Select the cloud provider. 3. Enter the provider's identifier (Optional: Add an alias): * **AWS**: Account ID * **GCP**: Project ID * **Azure**: Subscription ID * **Kubernetes**: Cluster ID * **M365**: Domain ID 4. Follow the guided instructions to add and authenticate your credentials. ## Start a Scan Once credentials are successfully added and validated, Prowler initiates a scan of your cloud environment. Click `Go to Scans` to monitor progress. ## View Results Review findings during scan execution in the following sections: * **Overview** – Provides a high-level summary of your scans. ![Overview](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/products/overview.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=96ceafb0329e6aec90333fa492da83af) * **Compliance** – Displays compliance insights based on security frameworks. ![Compliance](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=294db78346e837c814e48686a2d6b563) > For detailed usage instructions, refer to the [Prowler Cloud guide](/user-guide/tutorials/prowler-app), which also applies to Prowler Local Server. > [!NOTE] > > Prowler will automatically scan all configured providers every **24 hours**, ensuring your cloud environment stays continuously monitored. # Basic Usage Source: https://docs.prowler.com/getting-started/basic-usage/prowler-cli ## Running Prowler Running Prowler requires specifying the provider (e.g. `aws`, `gcp`, `azure`, `kubernetes`, `m365`, `github`, `iac` or `mongodbatlas`): > [!NOTE] > > If no provider is specified, AWS is used by default for backward compatibility with Prowler v2. ```console theme={null} prowler ``` ![Prowler Execution](https://mintcdn.com/prowler/9AoCN7Q_gXN7wF7l/images/short-display.png?fit=max\&auto=format\&n=9AoCN7Q_gXN7wF7l\&q=85\&s=ad991dd5d9346068631cd7b328b04408) > [!NOTE] > > Running the `prowler` command without options will use environment variable credentials. Refer to the Authentication section of each provider for credential configuration details. ## Verbose Output If you prefer the former verbose output, use: `--verbose`. This allows seeing more info while Prowler is running, minimal output is displayed unless verbosity is enabled. ## Report Generation By default, Prowler generates CSV, JSON-OCSF, and HTML reports. Additional provider-specific formats are available: * **JSON-ASFF** (AWS only): Used by AWS Security Hub * **SARIF** (IaC only): Used by GitHub Code Scanning To specify output formats, use the `-M` or `--output-modes` flag: ```console theme={null} prowler -M csv json-asff json-ocsf html ``` The HTML report is saved in the output directory, alongside other reports. It will look like this: ![Prowler Execution](https://mintcdn.com/prowler/LI3palQgXkn4dRXg/images/html-output.png?fit=max\&auto=format\&n=LI3palQgXkn4dRXg\&q=85\&s=ebf722f4914fcc25d4cad314a75dcc82) ## Listing Available Checks and Services List all available checks or services within a provider using `-l`/`--list-checks` or `--list-services`. ```console theme={null} prowler --list-checks prowler --list-services ``` ## Running Specific Checks or Services Execute specific checks or services using `-c`/`checks` or `-s`/`services`: ```console theme={null} prowler azure --checks storage_blob_public_access_level_is_disabled prowler aws --services s3 ec2 prowler gcp --services iam compute prowler kubernetes --services etcd apiserver ``` ## Excluding Checks and Services Checks and services can be excluded with `-e`/`--excluded-checks` or `--excluded-services`: ```console theme={null} prowler aws --excluded-checks s3_bucket_public_access prowler azure --excluded-services defender iam prowler gcp --excluded-services kms prowler kubernetes --excluded-services controllermanager ``` ## Additional Options Explore more advanced time-saving execution methods in the [Miscellaneous](/user-guide/cli/tutorials/misc) section. Access the help menu and view all available options with `-h`/`--help`: ```console theme={null} prowler --help ``` ## AWS Use a custom AWS profile with `-p`/`--profile` and/or specific AWS regions with `-f`/`--filter-region`: ```console theme={null} prowler aws --profile custom-profile -f us-east-1 eu-south-2 ``` > [!NOTE] > > By default, `prowler` will scan all AWS regions. See more details about AWS Authentication in the [Authentication Section](/user-guide/providers/aws/authentication) section. * **AWS Retrier and Timeout Configuration** [Added in:  5.42.0](https://github.com/prowler-cloud/prowler/releases/tag/5.42.0) Tune the Boto3 standard retrier and the endpoint timeouts when AWS throttles the scan or when some endpoints are unreachable from the network Prowler runs in: ```console theme={null} prowler aws --aws-retries-max-attempts 5 --aws-connect-timeout 5 --aws-read-timeout 30 ``` See the [Boto3 configuration](/user-guide/providers/aws/boto3-configuration) page for defaults and environment variables. ## Azure Azure requires specifying the auth method: ```console theme={null} # To use service principal authentication prowler azure --sp-env-auth # To use az cli authentication prowler azure --az-cli-auth # To use browser authentication prowler azure --browser-auth --tenant-id "XXXXXXXX" # To use managed identity auth prowler azure --managed-identity-auth ``` See more details about Azure Authentication in the [Authentication Section](/user-guide/providers/azure/authentication) By default, Prowler scans all accessible subscriptions. Scan specific subscriptions using the following flag (using az cli auth as example): ```console theme={null} prowler azure --az-cli-auth --subscription-ids ... ``` ## Google Cloud * **User Account Credentials** By default, Prowler uses **User Account credentials**. Configure accounts using: * `gcloud init` – Set up a new account. * `gcloud config set account ` – Switch to an existing account. Once configured, obtain access credentials using: `gcloud auth application-default login`. * **Service Account Authentication** Alternatively, you can use Service Account credentials: Generate and download Service Account keys in JSON format. Refer to [Google IAM documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for details. Provide the key file location using this argument: ```console theme={null} prowler gcp --credentials-file path ``` * **Scanning Specific GCP Projects** By default, Prowler scans all accessible GCP projects. Scan specific projects with the `--project-ids` flag: ```console theme={null} prowler gcp --project-ids ... ``` * **GCP Retry Configuration** Configure the maximum number of retry attempts for Google Cloud SDK API calls with the `--gcp-retries-max-attempts` flag: ```console theme={null} prowler gcp --gcp-retries-max-attempts 5 ``` This is useful when experiencing quota exceeded errors (HTTP 429) to increase the number of automatic retry attempts. ## Kubernetes Prowler enables security scanning of Kubernetes clusters, supporting both **in-cluster** and **external** execution. * **Non In-Cluster Execution** ```console theme={null} prowler kubernetes --kubeconfig-file path ``` > [!NOTE] > > If no `--kubeconfig-file` is provided, Prowler will use the default KubeConfig file location (`~/.kube/config`). * **In-Cluster Execution** To run Prowler inside the cluster, apply the provided YAML configuration to deploy a job in a new namespace: ```console theme={null} kubectl apply -f kubernetes/prowler-sa.yaml kubectl apply -f kubernetes/job.yaml kubectl apply -f kubernetes/prowler-role.yaml kubectl apply -f kubernetes/prowler-rolebinding.yaml kubectl get pods --namespace prowler-ns --> prowler-XXXXX kubectl logs prowler-XXXXX --namespace prowler-ns ``` > [!NOTE] > > By default, Prowler scans all namespaces in the active Kubernetes context. Use the `--context` flag to specify the context to be scanned and `--namespaces` to restrict scanning to specific namespaces. ## Microsoft 365 Microsoft 365 requires specifying the auth method: ```console theme={null} # To use service principal authentication for MSGraph and PowerShell modules prowler m365 --sp-env-auth # To use az cli authentication prowler m365 --az-cli-auth # To use browser authentication prowler m365 --browser-auth --tenant-id "XXXXXXXX" ``` See more details about M365 Authentication in the [Authentication Section](/user-guide/providers/microsoft365/authentication) section. ## GitHub Prowler enables security scanning of your **GitHub account**, including **Repositories**, **Organizations** and **Applications**. * **Supported Authentication Methods** Authenticate using one of the following methods: ```console theme={null} # Personal Access Token (PAT): prowler github --personal-access-token pat # OAuth App Token: prowler github --oauth-app-token oauth_token # GitHub App Credentials: prowler github --github-app-id app_id --github-app-key app_key ``` > [!NOTE] > > If no login method is explicitly provided, Prowler will automatically attempt to authenticate using environment variables in the following order of precedence: > > 1. `GITHUB_PERSONAL_ACCESS_TOKEN` > 2. `OAUTH_APP_TOKEN` > 3. `GITHUB_APP_ID` and `GITHUB_APP_KEY` ## Infrastructure as Code (IaC) Prowler's Infrastructure as Code (IaC) provider enables you to scan local or remote infrastructure code for security and compliance issues using [Trivy](https://trivy.dev/). This provider supports a wide range of IaC frameworks, allowing you to assess your code before deployment. ```console theme={null} # Scan a directory for IaC files prowler iac --scan-path ./my-iac-directory # Scan a remote GitHub repository (public or private) prowler iac --scan-repository-url https://github.com/user/repo.git # Authenticate to a private repo with GitHub username and PAT prowler iac --scan-repository-url https://github.com/user/repo.git \ --github-username --personal-access-token # Authenticate to a private repo with OAuth App Token prowler iac --scan-repository-url https://github.com/user/repo.git \ --oauth-app-token # Specify frameworks to scan (default: all) prowler iac --scan-path ./my-iac-directory --frameworks terraform kubernetes # Exclude specific paths prowler iac --scan-path ./my-iac-directory --exclude-path ./my-iac-directory/test,./my-iac-directory/examples ``` > [!NOTE] > > * `--scan-path` and `--scan-repository-url` are mutually exclusive; only one can be specified at a time. > * For remote repository scans, authentication can be provided via CLI flags or environment variables (`GITHUB_OAUTH_APP_TOKEN`, `GITHUB_USERNAME`, `GITHUB_PERSONAL_ACCESS_TOKEN`). CLI flags take precedence. > * The IaC provider does not require cloud authentication for local scans. > * It is ideal for CI/CD pipelines and local development environments. > * For more details on supported scanners, see the [Trivy documentation](https://trivy.dev/latest/docs/scanner/vulnerability/) See more details about IaC scanning in the [IaC Tutorial](/user-guide/providers/iac/getting-started-iac) section. ## MongoDB Atlas Prowler allows you to scan your MongoDB Atlas cloud database deployments for security and compliance issues. Authentication is done using MongoDB Atlas API key pairs: ```console theme={null} # Using command-line arguments prowler mongodbatlas --atlas-public-key --atlas-private-key # Using environment variables export ATLAS_PUBLIC_KEY= export ATLAS_PRIVATE_KEY= prowler mongodbatlas ``` You can filter scans to specific organizations or projects: ```console theme={null} # Scan specific project prowler mongodbatlas --atlas-project-id ``` See more details about MongoDB Atlas Authentication in [MongoDB Atlas Authentication](/user-guide/providers/mongodbatlas/authentication) ## Oracle Cloud Prowler allows you to scan your Oracle Cloud deployments for security and compliance issues. You have two options to authenticate: 1. OCI Config File Authentication: this config file can be generated using the OCI CLI with the `oci session authenticate` command or created manually using the OCI Console. For more details, see the [OCI Authentication Guide](/user-guide/providers/oci/authentication#oci-session-authentication). ```console theme={null} prowler oci ``` You can add different profiles to the config file to scan different tenancies or regions. In order to scan a specific profile, use the `--profile` flag: ```console theme={null} prowler oci --profile ``` 2. Instance Principal Authentication: when running Prowler on an OCI Compute instance, you can use Instance Principal authentication. For more details, see the [OCI Authentication Guide](/user-guide/providers/oci/authentication#instance-principal-authentication). ```console theme={null} prowler oci --use-instance-principal ``` See more details about Oracle Cloud Authentication in [Oracle Cloud Authentication](/user-guide/providers/oci/authentication) # Configuration Source: https://docs.prowler.com/getting-started/basic-usage/prowler-mcp Configure your MCP client to connect to Prowler MCP Server. ## Step 1: Get Your API Key > [!NOTE] > > **Authentication is optional**: Prowler Hub and Prowler Documentation features work without authentication. An API key is only required for Prowler tools (Prowler Cloud, Prowler Private Cloud, or Prowler Local Server). An API key authenticates the Prowler tools (Prowler Cloud, Prowler Private Cloud, or Prowler Local Server). To get the API key, please refer to the [API Keys](/user-guide/tutorials/prowler-app-api-keys) guide. > [!WARNING] > > Keep the API key secure. Never share it publicly or commit it to version control. ## Step 2: Configure Your MCP Host/Client Most users should use the **Cloud MCP Server** — it needs no installation and is maintained by Prowler. The [Local MCP Server](#local-mcp-server-configuration) configuration is provided afterwards for users who run the server themselves. * **Cloud MCP Server (HTTP)**: the managed server at `https://mcp.prowler.com/mcp` (or your own self-hosted HTTP server). * **Local MCP Server (STDIO)**: local installation only (runs as a subprocess of your MCP client). ### Step-by-Step Guides Per Agent The tabs below are a quick configuration reference. For a walkthrough with screenshots, troubleshooting, and client-specific caveats, follow the dedicated guide for your agent: > [card] [Claude Code](/user-guide/ai-agents/claude-code) > > Plugin vs. MCP-only, and which Claude surfaces work > [card] [Claude Desktop App (Chat)](/user-guide/ai-agents/claude-desktop) > > The Chat tab, via a local bridge > [card] [Codex](/user-guide/ai-agents/codex) > > CLI and the VS Code extension > [card] [Cursor](/user-guide/ai-agents/cursor) > > Global and project scopes > [card] [VS Code / Copilot](/user-guide/ai-agents/vscode) > > Agent mode with secure key prompts ## Cloud MCP Server Configuration (Recommended) Connect to the **Cloud MCP Server** at `https://mcp.prowler.com/mcp` over HTTP. This is the recommended path — no installation, always up to date. The same configuration works for a self-hosted HTTP server: just swap the URL. > [tab] Generic Native HTTP Support > > **Configuration:** > > ```json theme={null} > { > "mcpServers": { > "prowler": { > "url": "https://mcp.prowler.com/mcp", // or your self-hosted Prowler MCP Server URL > "headers": { > "Authorization": "Bearer " > } > } > } > } > ``` > [tab] Generic without Native HTTP Support > > **Configuration:** > > > [!WARNING] > > > > Avoid configuring MCP clients to run `npx mcp-remote` directly. `npx` can download and execute a new package version on each run. Install a reviewed version of `mcp-remote` in a dedicated local workspace, then point the MCP client to the installed binary. > > ```bash theme={null} > mkdir -p ~/.local/share/prowler-mcp-bridge > cd ~/.local/share/prowler-mcp-bridge > npm init -y > npm install --save-exact mcp-remote@0.1.38 > ``` > > ```json theme={null} > { > "mcpServers": { > "prowler": { > "command": "/absolute/path/to/.local/share/prowler-mcp-bridge/node_modules/.bin/mcp-remote", > "args": [ > "https://mcp.prowler.com/mcp", // or your self-hosted Prowler MCP Server URL > "--header", > "Authorization: Bearer ${PROWLER_API_KEY}" > ], > "env": { > "PROWLER_API_KEY": "" > } > } > } > } > ``` > > > [!NOTE] > > > > The `mcp-remote` tool acts as a bridge for clients that don't support HTTP natively. Learn more at [mcp-remote on npm](https://www.npmjs.com/package/mcp-remote). ## Local MCP Server Configuration STDIO mode is only available when running the **Local MCP Server** on your own machine. See the [Installation guide](/getting-started/installation/prowler-mcp) to set it up first. > [tab] Generic uvx installation > > **Run from source or local installation** > > ```json theme={null} > { > "mcpServers": { > "prowler": { > "command": "uvx", > "args": ["/absolute/path/to/prowler/mcp_server/"], > "env": { > "PROWLER_API_KEY": "", > "API_BASE_URL": "https://api.prowler.com/api/v1" > } > } > } > } > ``` > > > [!NOTE] > > > > Replace `/absolute/path/to/prowler/mcp_server/` with the actual path. The `API_BASE_URL` is optional and defaults to Prowler Cloud API. > [tab] Generic Docker installation > > **Run with Docker image** > > ```json theme={null} > { > "mcpServers": { > "prowler": { > "command": "docker", > "args": [ > "run", > "--rm", > "-i", > "--env", > "PROWLER_API_KEY=", > "--env", > "API_BASE_URL=https://api.prowler.com/api/v1", > "prowlercloud/prowler-mcp" > ] > } > } > } > ``` > > > [!NOTE] > > > > The `API_BASE_URL` is optional and defaults to Prowler Cloud API. ## Step 3: Start Using Prowler MCP Restart your MCP client and start asking questions: * *"Show me all critical findings from my AWS accounts"* * *"What does the S3 bucket public access check do?"* * *"Onboard this new AWS account in my Prowler Organization"* ## Authentication Methods Prowler MCP Server supports two authentication methods to connect to Prowler (Prowler Cloud, Prowler Private Cloud, or Prowler Local Server): ### API Key (Recommended) Use your Prowler API key directly in the Bearer token: ``` Authorization: Bearer ``` This is the recommended method for most users. ### JWT Token Alternatively, obtain a JWT token from Prowler: ```bash theme={null} curl -X POST https://api.prowler.com/api/v1/tokens \ -H "Content-Type: application/vnd.api+json" \ -H "Accept: application/vnd.api+json" \ -d '{ "data": { "type": "tokens", "attributes": { "email": "your-email@example.com", "password": "your-password" } } }' ``` Use the returned JWT token in place of the API key: ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` > [!WARNING] > > JWT tokens are only valid for 30 minutes. You need to generate a new token if you want to continue using the MCP server. ## Troubleshooting ### Server Not Detected * Restart your MCP client after configuration changes * Check the configuration file syntax (valid JSON) * Review client logs for specific error messages * Verify the server URL is correct ### Authentication Failures **Error: Unauthorized (401)** * Verify your API key is correct * Ensure the key hasn't expired * Check you're using the right API endpoint ### Connection Issues **Cannot Reach Server:** * Verify the server URL is correct * Check network connectivity * For local servers, ensure the server is running * Check firewall settings ## Security Best Practices 1. **Protect Your API Key** * Never commit API keys to version control. * Use environment variables or secure vaults. * Rotate keys regularly. 2. **Network Security** * Use HTTPS for production deployments. * Restrict network access to the MCP server. * Consider VPN for remote access. 3. **Least Privilege** * API key gives the permission of the user who created the key, make sure to use the key with the minimal required permissions. * Review the tools that are gonna be used and how they are gonna be used to avoid prompt injections or unintended behavior. ## Next Steps Now that your MCP server is configured: > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools ## Getting Help Need assistance with configuration? * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Tools Reference Source: https://docs.prowler.com/getting-started/basic-usage/prowler-mcp-tools Complete reference guide for all tools available in the Prowler MCP Server. Tools are organized by namespace. ## Tool Categories Summary | Category | Tool Count | Authentication Required | Availability | | - | - | - | - | | Prowler Hub | 10 tools | No | Cloud and Local MCP Server | | Prowler Documentation | 2 tools | No | Cloud and Local MCP Server | | Prowler Cloud, Private Cloud & Local Server | 49 tools | Yes | Cloud and Local MCP Server | | Prowler Cloud management | 40 tools | Yes | Cloud MCP Server only | > [!NOTE] > > 48 of the 49 Prowler tools are available on both servers. `prowler_schedule_daily_scan` is the exception: it is Local-only, because the Cloud MCP Server supersedes it with the `prowler_cloud_*` [Scan Scheduling](#scan-scheduling) tools. `prowler_send_findings_to_jira` is exposed by both servers but accepts two [extra parameters](#jira-operations) on the Cloud MCP Server. ## Tool Naming Convention All tools follow a consistent naming pattern with prefixes: * `prowler_hub_*` - Prowler Hub catalog and compliance tools * `prowler_docs_*` - Prowler documentation search and retrieval * `prowler_*` - Prowler Cloud, Prowler Private Cloud & Prowler Local Server management tools * `prowler_cloud_*` - Prowler Cloud-only management tools > [!NOTE] > > `prowler_cloud_*` tools are exposed only by the [Cloud MCP Server](/getting-started/products/prowler-mcp#cloud-vs-local-mcp-server) at `https://mcp.prowler.com/mcp`, because they manage features that exist only in Prowler Cloud. Every other tool is available on both the Cloud and Local MCP Server. ## Prowler Tools Manage your Prowler deployment — Prowler Cloud, Prowler Private Cloud, or Prowler Local Server. **Requires authentication.** > [!NOTE] > > These tools require a valid API key. See the [Configuration Guide](/getting-started/basic-usage/prowler-mcp) for authentication setup. ### Findings Management Tools for searching, viewing, and analyzing security findings across all cloud providers. * **`prowler_search_security_findings`** - Search and filter security findings with advanced filtering options (severity, status, provider, region, service, check ID, date range, muted status) * **`prowler_get_finding_details`** - Get comprehensive details about a specific finding including remediation guidance, check metadata, and resource relationships * **`prowler_get_findings_overview`** - Get aggregate statistics and trends about security findings as a markdown report ### Finding Groups Management Tools for listing finding groups aggregated by check ID, viewing complete group counters, and drilling down into affected resources. * **`prowler_list_finding_groups`** - List latest or historical finding groups with filters for provider, region, service, resource, category, check, severity, status, muted state, delta, date range, and sorting * **`prowler_get_finding_group_details`** - Get complete details for a specific finding group including counters, description, timestamps, and impacted providers * **`prowler_list_finding_group_resources`** - List actionable unmuted resources affected by a finding group by default, including nested resource and provider data plus the `finding_id` for remediation details. Set `include_muted` to include suppressed resources ### Provider Management Tools for managing cloud provider connections in Prowler. * **`prowler_search_providers`** - Search and view configured providers with their connection status * **`prowler_connect_provider`** - Register and connect a provider with credentials for security scanning * **`prowler_delete_provider`** - Permanently remove a provider from Prowler ### Scan Management Tools for managing and monitoring security scans. * **`prowler_list_scans`** - List and filter security scans across all providers * **`prowler_get_scan`** - Get comprehensive details about a specific scan (progress, duration, resource counts) * **`prowler_trigger_scan`** - Trigger a manual security scan for a provider * **`prowler_schedule_daily_scan`** - Schedule automated daily scans for continuous monitoring (**Local MCP Server only**) * **`prowler_update_scan`** - Update scan name for better organization > [!NOTE] > > `prowler_schedule_daily_scan` is the scheduling tool for a self-hosted deployment, and it only does one thing: a daily scan. The Cloud MCP Server does not expose it — Prowler Cloud replaces it with the richer [Scan Scheduling](#scan-scheduling) tools, which add interval, weekly, and monthly frequencies, per-provider schedule retrieval, and bulk apply across providers. ### Resources Management Tools for searching, viewing, and analyzing cloud resources discovered by Prowler. * **`prowler_list_resources`** - List and filter cloud resources with advanced filtering options (provider, region, service, resource type, tags) * **`prowler_get_resource`** - Get comprehensive details about a specific resource including configuration, metadata, and finding relationships * **`prowler_get_resource_events`** - Get the timeline of cloud API actions performed on a resource (AWS CloudTrail). Shows who did what and when, with full request/response payloads * **`prowler_get_resources_overview`** - Get aggregate statistics about cloud resources as a markdown report ### Muting Management Tools for managing finding muting, including pattern-based bulk muting (mutelist) and finding-specific mute rules. #### Mutelist (Pattern-Based Muting) * **`prowler_get_mutelist`** - Retrieve the current mutelist configuration for the tenant * **`prowler_set_mutelist`** - Create or update the mutelist configuration for pattern-based bulk muting * **`prowler_delete_mutelist`** - Remove the mutelist configuration from the tenant #### Mute Rules (Finding-Specific Muting) * **`prowler_list_mute_rules`** - Search and filter mute rules with pagination support * **`prowler_get_mute_rule`** - Retrieve comprehensive details about a specific mute rule * **`prowler_create_mute_rule`** - Create a new mute rule to mute specific findings with documentation and audit trail * **`prowler_update_mute_rule`** - Update a mute rule's name, reason, or enabled status * **`prowler_delete_mute_rule`** - Delete a mute rule from the system ### Integrations Management Tools for managing where Prowler sends its results: Amazon S3 buckets, AWS Security Hub, and Jira. Requires the **Manage Integrations** permission. #### Integration Lifecycle * **`prowler_list_integrations`** - List the configured integrations with their enabled and connection state, optionally filtered by integration type * **`prowler_get_integration`** - Get an integration with its complete, type-specific configuration (bucket and output directory, Security Hub settings and enabled regions, or Jira projects and issue types) * **`prowler_update_integration`** - Update credentials, configuration, attached providers, or enabled state. Configuration changes are merged with the current one, and the connection is re-checked automatically whenever credentials, configuration, or attached providers change * **`prowler_delete_integration`** - Permanently remove an integration and its stored credentials * **`prowler_test_integration_connection`** - Check an integration connection and refresh the configuration Prowler discovers from the remote system (Jira projects, Security Hub regions) #### Integration Setup * **`prowler_create_amazon_s3_integration`** - Export scan outputs (CSV, HTML, OCSF JSON, compliance reports) to an S3 bucket, using an IAM role or static credentials * **`prowler_create_aws_security_hub_integration`** - Send findings to AWS Security Hub in ASFF format for a single AWS provider, reusing the provider credentials or dedicated ones * **`prowler_create_jira_integration`** - Connect an Atlassian Jira site so findings can be turned into work items. Tenant-wide, not attached to any provider #### Jira Operations * **`prowler_get_jira_issue_types`** - List the issue types available in a Jira project, fetched live from Jira * **`prowler_send_findings_to_jira`** - Create Jira work items from findings, each carrying the check title, severity, status, provider, region, resource, risk, and remediation steps. Select the findings either by ID with `finding_ids`, or — on Prowler Cloud only — by check with `check_ids`, and choose between one work item per finding or one per check with `dispatch_mode` > [!NOTE] > > `check_ids` and `dispatch_mode` are **Prowler Cloud only**: > > * **`check_ids`** - Send the failing findings of a check (for example `s3_bucket_public_access`) without listing their IDs. Prowler resolves them server-side, taking only the failed findings of the latest completed scan of every provider. Get the check IDs from `prowler_list_finding_groups`. Exactly one of `finding_ids` or `check_ids` is required — Prowler combines both filters, so sending both would only dispatch their intersection. A Local MCP Server rejects `check_ids` with a client error. > * **`dispatch_mode`** - `individual` (the default) creates one work item per finding. `grouped` creates one work item per check instead, listing up to 50 affected resources and linking back to the finding group in Prowler Cloud, which keeps a noisy check to a single ticket. Grouped dispatch only covers failed, unmuted findings of the latest completed scan of every provider. A Local MCP Server ignores `dispatch_mode` instead of rejecting it, and creates one work item per finding. > > In `grouped` mode the response counters change meaning: `created_count` counts work items (one per check) rather than findings, `failed_count` counts the entries of the new `failed_groups` field, and `failed_groups` details each failure with its reason and the `check_id` whose work item could not be created. > [!WARNING] > > `prowler_send_findings_to_jira` creates real work items that Prowler cannot delete or update afterwards. Only retry the same dispatch when the previous response returned `safe_to_retry: true`, otherwise the work items already created are duplicated. Combining `check_ids` with the default `individual` mode opens one work item per failing resource, which can be hundreds of them — use `dispatch_mode="grouped"` to keep it to one per check. ### Attack Paths Analysis Tools for analyzing privilege escalation chains and security misconfigurations using graph-based analysis. Attack Paths maps relationships between cloud resources, permissions, and security findings to detect how privileges can be escalated and how misconfigurations can be exploited. * **`prowler_list_attack_paths_scans`** - List Attack Paths scans with filtering by provider, provider type, and scan state (available, scheduled, executing, completed, failed, cancelled) * **`prowler_list_attack_paths_queries`** - Discover available Attack Paths queries for a completed scan, including query names, descriptions, and required parameters * **`prowler_run_attack_paths_query`** - Execute an Attack Paths query against a completed scan and retrieve graph results with nodes (cloud resources, findings, virtual nodes) and relationships (access paths, role assumptions, security group memberships) * **`prowler_get_attack_paths_cartography_schema`** - Retrieve the Cartography graph schema (node labels, relationships, properties) for writing accurate custom openCypher queries ### Compliance Management Tools for viewing compliance status and framework details across all cloud providers. * **`prowler_get_compliance_overview`** - Get high-level compliance status across all frameworks for a specific scan or provider, including pass/fail statistics per framework * **`prowler_get_compliance_framework_state_details`** - Get detailed requirement-level breakdown for a specific compliance framework, including failed requirements and associated finding IDs ### User Management Tools for viewing the users in your tenant and identifying the authenticated user. * **`prowler_list_users`** - List the users in the tenant with their names and emails * **`prowler_get_user`** - Get detailed information about a specific user by ID, including join date and role/membership IDs * **`prowler_get_current_user`** - Identify which user the current credentials authenticate as ### Role Management Tools for browsing RBAC roles and managing the role assigned to a user. A user holds exactly one role, so setting a role replaces the one they held before. * **`prowler_list_roles`** - List the roles defined in the tenant with their permission scope * **`prowler_get_role`** - Get detailed information about a specific role by ID, including granted capabilities, visibility scope, assigned users, and provider groups * **`prowler_get_user_roles`** - List the roles assigned to a specific user, with the capabilities each role grants * **`prowler_set_user_role`** - Set the role a user holds, replacing the role they had before (idempotent) ## Prowler Cloud Tools Manage Prowler Cloud-only features and configuration. **Requires authentication.** > [!NOTE] > > These tools are available **only on the Cloud MCP Server** (`https://mcp.prowler.com/mcp`). A Local MCP Server does not expose them, because the features they manage exist only in Prowler Cloud. ### Organizations Tools for onboarding a cloud provider organization as a whole — an AWS Organization, an Azure tenant with its management groups, or a GCP organization with its folders. An organization holds org-level credentials, discovers the real account, subscription, or project structure in the cloud, and turns a selection from that discovery into Prowler providers linked into a hierarchy of nodes. Every tool that changes something — creating, updating, deleting, discovering, applying a discovery, or adjusting provider membership — requires the **Manage Providers** permission; listing and reading do not. > [!NOTE] > > Use these tools for the whole organization. To register providers one by one, use the [Provider Management](#provider-management) tools instead; to build arbitrary RBAC buckets of providers, use provider groups. * **`prowler_cloud_list_organizations`** - Browse the registered organizations with lightweight data (name, type, external id, provider and node counts), filtered by type or cloud-side external id * **`prowler_cloud_get_organization`** - Get one organization in full: attributes, linked providers, credentials status, latest discovery, and the OU / management group / folder hierarchy. Set `include_hierarchy` to `false` to skip the tree on large organizations * **`prowler_cloud_create_organization`** - Register an organization, optionally storing its org-level credentials in the same call. Idempotent: an organization with the same type and external id is reused and its credentials rotated, reported as `created: false` * **`prowler_cloud_update_organization`** - Rename an organization, replace its metadata, and/or create or rotate its org-level credentials. `org_type` and `external_id` are immutable after creation * **`prowler_cloud_delete_organization`** - Delete an organization, its entire hierarchy, and every linked provider * **`prowler_cloud_discover_organization`** - Enumerate the real cloud structure: AWS accounts and OUs, Azure subscriptions and management groups, or GCP projects and folders. Each item comes back with its registration state so you can choose what to onboard * **`prowler_cloud_apply_organization_discovery`** - Turn a discovery selection into Prowler providers and hierarchy nodes * **`prowler_cloud_manage_organization_providers`** - Manually `add`, `replace`, or `remove` the providers linked to an organization or to one of its hierarchy nodes. Providers are detached, never deleted ### Scan Configurations Tools for managing reusable scan configurations — per-provider check and compliance selections — and attaching them to providers. Providers without a configuration attached use the default. * **`prowler_cloud_list_scan_configurations`** - List and filter the scan configurations defined in the tenant * **`prowler_cloud_get_scan_configuration`** - Retrieve a scan configuration including its full configuration body * **`prowler_cloud_get_scan_configuration_schema`** - Fetch the JSON Schema describing the keys a valid configuration body may set, optionally filtered to a single provider type * **`prowler_cloud_create_scan_configuration`** - Create a scan configuration and optionally attach it to providers * **`prowler_cloud_update_scan_configuration`** - Update a configuration's name, body, and/or attached providers * **`prowler_cloud_delete_scan_configuration`** - Delete a scan configuration; attached providers revert to the default ### Findings Triage Tools for recording a review decision on a finding and documenting the reasoning. Triage is keyed on the stable finding UID returned by `prowler_search_security_findings` and `prowler_get_finding_details`. > [!NOTE] > > Triage is distinct from [muting](#muting-management). Use mute rules and the mutelist to **suppress** findings; use triage to **record a decision** and its rationale while the finding stays visible. See the [Findings Triage tutorial](/user-guide/tutorials/prowler-app-findings-triage). * **`prowler_cloud_list_finding_triages`** - List and filter persisted triage records by status, provider, check, and more * **`prowler_cloud_get_finding_triage`** - Retrieve a single finding's triage state by finding UID * **`prowler_cloud_set_finding_triage_status`** - Set a finding's triage status (`open`, `under_review`, `remediating`, `risk_accepted`, `false_positive`), optionally attaching a note. The `resolved` and `reopened` statuses are system-managed and cannot be set directly * **`prowler_cloud_list_finding_triage_notes`** - List the notes attached to a finding's triage, newest first * **`prowler_cloud_create_finding_triage_note`** - Add a new note to a finding's triage * **`prowler_cloud_update_finding_triage_note`** - Update the body of an existing note * **`prowler_cloud_delete_finding_triage_note`** - Delete a note from a finding's triage ### Scan Scheduling Tools for configuring recurring scans. One schedule exists per provider, with daily, interval, weekly, or monthly frequency. These replace the Local-only `prowler_schedule_daily_scan`, which can only set up a daily scan. See the [Scan Scheduling tutorial](/user-guide/tutorials/prowler-scan-scheduling). * **`prowler_cloud_list_scan_schedules`** - List scan schedules, one per visible provider * **`prowler_cloud_get_scan_schedule`** - Retrieve a provider's schedule including all per-frequency fields * **`prowler_cloud_set_scan_schedule`** - Configure or update a single provider's recurring scan schedule * **`prowler_cloud_bulk_set_scan_schedules`** - Apply one schedule to many providers at once * **`prowler_cloud_delete_scan_schedule`** - Delete a provider's scan schedule ### Alerts Tools for notifying recipients when scan results match a rule condition. See the [Alerts tutorial](/user-guide/tutorials/prowler-alerts). #### Alert Rules * **`prowler_cloud_list_alert_rules`** - List and filter the custom alert rules defined in the tenant * **`prowler_cloud_get_alert_rule`** - Retrieve an alert rule including its condition DSL and recipient emails * **`prowler_cloud_create_alert_rule`** - Create a tenant-scoped alert rule * **`prowler_cloud_update_alert_rule`** - Update an alert rule; only the fields provided change * **`prowler_cloud_delete_alert_rule`** - Delete an alert rule * **`prowler_cloud_list_alert_rule_events`** - List the fired-alert history for a single rule, newest first * **`prowler_cloud_build_alert_rule_condition`** - Build a condition from a findings filter and dry-run it in one call to preview what would match. Nothing is persisted #### Alert Recipients * **`prowler_cloud_list_alert_recipients`** - List alert recipients with their confirmation status * **`prowler_cloud_get_alert_recipient`** - Retrieve a single recipient with its confirmation status * **`prowler_cloud_create_alert_recipient`** - Register a new recipient email * **`prowler_cloud_resend_alert_recipient_confirmation`** - Re-send the confirmation email to a pending or unsubscribed recipient * **`prowler_cloud_delete_alert_recipient`** - Delete an alert recipient #### Alert Events * **`prowler_cloud_list_alert_events`** - List the fired alert events for the tenant * **`prowler_cloud_get_alert_event`** - Retrieve a single alert event including its matched rule and scan ## Prowler Hub Tools Access Prowler's security check catalog and compliance frameworks. **No authentication required.** Tools follow a **two-tier pattern**: lightweight listing for browsing + detailed retrieval for complete information. ### Check Discovery and Details * **`prowler_hub_list_checks`** - List security checks with lightweight data (id, title, severity, provider) and advanced filtering options * **`prowler_hub_semantic_search_checks`** - Full-text search across check metadata with lightweight results * **`prowler_hub_get_check_details`** - Get comprehensive details for a specific check including risk, remediation guidance, and compliance mappings ### Check Code * **`prowler_hub_get_check_code`** - Fetch the Python implementation code for a security check * **`prowler_hub_get_check_fixer`** - Fetch the automated fixer code for a check (if available) ### Compliance Frameworks * **`prowler_hub_list_compliances`** - List compliance frameworks with lightweight data (id, name, provider) and filtering options * **`prowler_hub_semantic_search_compliances`** - Full-text search across compliance frameworks with lightweight results * **`prowler_hub_get_compliance_details`** - Get comprehensive compliance details including requirements and mapped checks ### Providers Information * **`prowler_hub_list_providers`** - List Prowler official providers * **`prowler_hub_get_provider_services`** - Get available services for a specific provider ## Prowler Documentation Tools Search and access official Prowler documentation. **No authentication required.** * **`prowler_docs_search`** - Search the official Prowler documentation using full-text search with the `term` parameter * **`prowler_docs_get_document`** - Retrieve the full markdown content of a specific documentation file using the path from search results ## Usage Tips * Use natural language to interact with the tools through your AI assistant * Tools can be combined for complex workflows * Filter options are available on most list tools * Authentication is only required for the `prowler_*` and `prowler_cloud_*` tools; Prowler Hub and Prowler Documentation tools work without a key * If a `prowler_cloud_*` tool is missing from your client, you are connected to a Local MCP Server — point it at `https://mcp.prowler.com/mcp` instead ## Additional Resources * [MCP Protocol Specification](https://modelcontextprotocol.io) * [Prowler API Documentation](https://api.prowler.com/api/v1/docs) * [Prowler Hub API](https://hub.prowler.com/api/docs) * [GitHub Repository](https://github.com/prowler-cloud/prowler) # AWS Security Hub Source: https://docs.prowler.com/getting-started/comparison/awssecurityhub AWS offers [two complementary services](https://docs.aws.amazon.com/securityhub/latest/userguide/what-are-securityhub-services.html) under the Security Hub name, and Prowler works alongside both: * **AWS Security Hub CSPM:** The service formerly called AWS Security Hub. It evaluates resources against security standards and best practices, and [ingests findings from AWS services and AWS Partner Network solutions](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-providers.html), including Prowler, in the AWS Security Finding Format (ASFF). * **AWS Security Hub:** A [unified cloud security service](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub-v2.html) that correlates findings from Security Hub CSPM, Amazon GuardDuty, Amazon Inspector, and Amazon Macie in the Open Cybersecurity Schema Framework (OCSF) to prioritize the most critical risks. Many teams use Prowler for broad, customizable posture checks across every environment they run, and send Prowler findings to Security Hub CSPM to keep a single view of AWS security. ## Key Features and Strengths * **Managed AWS-Native Service:** Security Hub runs inside AWS with no infrastructure to operate and is available from the AWS Management Console. * **Centralized Findings for AWS:** Security Hub CSPM consolidates findings from AWS services such as GuardDuty, Inspector, Macie, AWS Config, and IAM Access Analyzer, as well as from [partner products](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-providers.html) such as Prowler. * **Managed Security Standards:** Security Hub CSPM evaluates [standards](https://docs.aws.amazon.com/securityhub/latest/userguide/standards-reference.html) such as AWS Foundational Security Best Practices, CIS AWS Foundations Benchmark, PCI DSS, and NIST SP 800-53. * **Microsoft Azure Coverage:** Both services integrate with Microsoft Azure, including automated checks against the CIS Microsoft Azure Foundations Benchmark v4.0 and Azure Foundational Best Practices standards. See the integration guides for [Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-v2-azure.html) and [Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-azure.html). * **Risk Correlation:** Security Hub correlates findings across AWS security services to detect exposures and visualize attack paths. * **AWS-Native Automation:** [Automation rules and Amazon EventBridge](https://docs.aws.amazon.com/securityhub/latest/userguide/automations.html) update findings and trigger automated response. ## Considerations * **Coverage Centered on AWS and Azure:** Other clouds, Kubernetes, and SaaS platforms such as Microsoft 365, GitHub, Google Workspace, or Okta fall outside the built-in standards. * **Dependency on AWS Config:** Security Hub CSPM uses AWS Config rules to generate control findings for AWS resources. When the unified Security Hub is also enabled, Security Hub CSPM [creates a service-linked configuration recorder automatically](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-setup-prereqs.html). When Security Hub CSPM runs without the unified Security Hub, AWS Config must be enabled manually and recording resources in each region. * **Regional Configuration:** Security Hub CSPM is enabled per account and region. [Central configuration](https://docs.aws.amazon.com/securityhub/latest/userguide/central-configuration-intro.html) through AWS Organizations simplifies this for multi-account environments. * **Partner Findings Go to Security Hub CSPM:** Third-party partner findings, including Prowler findings, are sent to Security Hub CSPM. The unified Security Hub [does not receive findings from third-party partner tools](https://aws.amazon.com/security-hub/faqs/). ## Prowler Prowler is an open-source, multi-cloud security platform available as Prowler Cloud, Prowler Private Cloud, Prowler CLI, and Prowler Local Server. It offers extensive customization and flexibility for organizations with complex or multi-cloud environments. ## Main Advantages of Prowler * **Multi-Region Scanning by Default:** Prowler scans every AWS region without additional configuration and without enabling services such as AWS Config. To cover multiple AWS accounts, Prowler assumes a role in each account: onboard the accounts in Prowler Cloud through [AWS Organizations](/user-guide/tutorials/prowler-cloud-aws-organizations), or run Prowler CLI per account as described in [AWS Organizations in Prowler](/user-guide/providers/aws/organizations). * **Minimal Setup Requirements:** Prowler only needs a role with the appropriate read permissions to start scanning. * **Versatile Execution Environment:** Prowler runs from Prowler Cloud, a local workstation, a container, AWS CloudShell, CI/CD pipelines, or another AWS account or cloud provider by assuming a role. * **Flexible Results Storage and Sharing:** Prowler stores results locally or directly in an Amazon S3 bucket for analysis and collaborative security assessments. * **Customizable Reporting:** Prowler exports results in JSON, CSV, OCSF, ASFF, and HTML formats. * **Custom Checks and Compliance Frameworks:** Custom checks, remediations, and compliance frameworks can be written in minutes to match specific security policies. * **Extensive Compliance Support:** Prowler supports 40+ compliance framework versions for AWS, including CIS AWS Foundations Benchmark, AWS Foundational Security Best Practices, AWS Well-Architected Framework, NIST SP 800-53, NIST CSF, PCI DSS, ISO/IEC 27001, SOC 2, HIPAA, GDPR, NIS2, ENS, and FedRAMP, and 100+ framework versions across all providers. Explore them in [Prowler Hub](https://hub.prowler.com/compliance). * **Multi-Cloud and Beyond:** Prowler provides 2,200+ checks across 20+ providers, including AWS, Microsoft Azure, Google Cloud, Kubernetes (including Amazon EKS), Microsoft 365, GitHub, Google Workspace, Okta, Oracle Cloud Infrastructure, Alibaba Cloud, infrastructure as code, and container images. Explore all checks in [Prowler Hub](https://hub.prowler.com/check). * **All-Region Checks:** Prowler runs its checks in all regions, regardless of AWS Config resource type support. ## Using Prowler With AWS Security Hub Prowler is an official partner integration of Security Hub CSPM. Prowler findings are sent in ASFF and appear next to findings from AWS services, so teams keep the AWS-native view while adding Prowler coverage: * **Prowler Cloud, Prowler Private Cloud, and Prowler Local Server:** Configure the [AWS Security Hub integration](/user-guide/tutorials/prowler-app-security-hub-integration) to export findings automatically after each scan. * **Prowler CLI:** Add the `--security-hub` flag to send findings, as described in [AWS Security Hub Integration with Prowler](/user-guide/providers/aws/securityhub). * **Cost Control:** In Prowler CLI, `--send-sh-only-fails` sends only failed findings to Security Hub CSPM while keeping all findings in Prowler outputs. `--status FAIL` also limits what is sent, but it removes passing findings from Prowler outputs as well. ## Comparison Summary ### Scope and Environment * **Security Hub** suits organizations that want a managed, AWS-native service to monitor, correlate, and automate security across AWS, with additional coverage for Microsoft Azure. * **Prowler** suits organizations that need consistent, customizable checks across AWS, Azure, Google Cloud, Kubernetes, SaaS platforms, and more, from a single open-source tool. ### Setup and Maintenance * **Security Hub** is enabled per account and region, and Security Hub CSPM relies on AWS Config for control findings on AWS resources, which must be set up manually unless the unified Security Hub is also enabled. AWS Organizations and central configuration help manage this at scale. * **Prowler** only needs the appropriate permissions and runs from many environments, without requiring additional AWS services. ### Customization and Flexibility * **Security Hub** offers managed standards and controls, plus automation through AWS services. * **Prowler** allows highly customizable checks, remediations, and compliance frameworks that adapt quickly to organizational needs and regulatory changes. ### Cost Efficiency * **Security Hub** uses resource-based pricing, with finding ingestion included. Refer to [AWS Security Hub pricing](https://aws.amazon.com/security-hub/pricing/). * **Security Hub CSPM** is billed per security check and per finding ingestion event above a monthly free tier. Refer to [AWS Security Hub CSPM pricing](https://aws.amazon.com/security-hub/cspm/pricing/). * **Prowler** can reduce Security Hub CSPM finding ingestion costs with `--send-sh-only-fails`, which sends only failed findings while keeping complete results in its own outputs or in Amazon S3. ### Multi-Cloud and Multi-Region Support * **Security Hub** covers AWS and Microsoft Azure. * **Prowler** is inherently multi-region and multi-cloud, with consistent checks across cloud, Kubernetes, and SaaS environments. ## Conclusion AWS Security Hub and Prowler work best together: * **AWS Security Hub** provides a managed, AWS-native place to aggregate, correlate, and act on security findings. * **Prowler** adds transparent, customizable checks and broad compliance coverage across AWS and every other environment an organization runs, and sends its findings to Security Hub CSPM. Organizations focused on AWS can rely on Security Hub as their central view and use Prowler to extend checks and compliance coverage. Organizations with multi-cloud or SaaS footprints can use Prowler as a consistent posture layer across all environments while keeping AWS findings in Security Hub. # GCP Cloud Security Command Center (Cloud SCC) Source: https://docs.prowler.com/getting-started/comparison/gcp Google Cloud Security Command Center (Cloud SCC) is a centralized security and risk management platform for Google Cloud Platform (GCP). It provides visibility into assets, vulnerabilities, and threats across GCP environments, helping organizations to manage and improve their security posture. ## Key Features and Strengths * **Centralized Security Visibility:** Cloud SCC provides a single pane of glass to monitor the security and risk status across your GCP resources. It aggregates findings from various GCP security services, such as Security Health Analytics, Web Security Scanner, and Event Threat Detection. * **Asset Inventory and Classification:** Cloud SCC offers comprehensive asset discovery and classification across GCP, giving security teams a detailed inventory of their cloud resources, including their configurations and security states. * **Threat Detection and Monitoring:** The platform integrates with GCP’s threat detection tools, such as Google’s Event Threat Detection, which analyzes logs for suspicious activities and potential threats. * **Compliance Monitoring:** Cloud SCC helps monitor compliance with various regulatory standards by continuously assessing your GCP resources against best practices and security benchmarks. * **Automated Remediation:** Cloud SCC can trigger automated responses to security findings through integrations with Google Cloud Functions or other orchestration tools, helping to mitigate risks quickly. * **Native GCP Integration:** Cloud SCC is deeply integrated with the GCP ecosystem, offering seamless operation within Google Cloud environments and leveraging Google's extensive security expertise. ## Limitations * **GCP-Centric:** While Cloud SCC is powerful within the GCP ecosystem, it is primarily focused on GCP and does not natively extend to multi-cloud environments without additional tools or connectors. * **Cost Considerations:** As a managed service within GCP, costs can scale with the amount of data ingested and the complexity of the environment, especially as additional features or higher volumes of data are used. * **Dependency on GCP Services:** Cloud SCC's capabilities depend on other GCP services being enabled, such as Security Health Analytics and Web Security Scanner, which may increase overall complexity and cost. ## Prowler Prowler is an open-source, multi-cloud security tool designed to perform detailed security assessments and compliance checks across diverse cloud environments, including AWS, Azure, GCP, and Kubernetes. Here are the key advantages of Prowler when compared to GCP Cloud SCC: ## Main Advantages of Prowler * **Multi-Region and Multi-Account Scanning by Default:** * Prowler inherently supports multi-region and multi-account scanning across multiple cloud providers, including GCP, AWS, Azure, and Kubernetes. It does not require additional configuration to perform these scans, making it immediately useful for organizations operating in multiple cloud environments. * **Minimal Setup Requirements:** * Prowler requires only appropriate roles and permissions to start scanning. It doesn’t necessitate enabling specific services within GCP, which can simplify the setup process and reduce dependencies. * **Versatile Execution Environment:** * Prowler can be run from various environments, such as a local workstation, container, Google Cloud Shell, or even other cloud providers by assuming a role. This versatility allows for flexible deployment and integration into existing security operations. * **Flexible Results Storage and Sharing:** * Prowler results can be stored in an S3 bucket for AWS, Google Cloud Storage (GCS) for GCP, or locally, allowing for quick analysis and easy sharing. This flexibility is particularly advantageous for multi-cloud security assessments and collaborative security processes. * **Customizable Reporting and Analysis:** * Prowler supports exporting results in multiple formats, including JSON, CSV, OCSF format, and static HTML reports. These reports can be tailored to specific needs and easily integrated with other security tools or dashboards, providing comprehensive insights across all cloud environments. * **SIEM Integration and Cost Efficiency:** * Prowler can be configured to send findings directly into SIEM systems, including those integrated with GCP or other platforms. By sending only failed findings or selected results, Prowler helps manage costs associated with data ingestion and analysis in SIEM platforms. * **Custom Checks and Compliance Frameworks:** * Prowler allows for the creation of custom security checks, remediation actions, and compliance frameworks, providing flexibility that can be adapted to the unique security policies and regulatory requirements of an organization. * **Extensive Compliance Support:** * Prowler supports over 27 compliance frameworks out of the box, with capabilities to extend these frameworks to GCP environments as well as other cloud platforms. This broad compliance coverage ensures that organizations can maintain adherence to various regulatory requirements. * **Kubernetes and Multi-Cloud Support:** * Prowler is designed to support security assessments across cloud environments, including Kubernetes clusters and GCP. This multi-cloud capability is essential for organizations that operate across diverse cloud platforms and require consistent security posture management. * **All-Region Checks:** * Prowler runs all checks in all regions by default, ensuring comprehensive coverage across an organization’s cloud resources, regardless of the region or cloud provider. ## Comparison Summary ### Scope and Environment * **GCP Cloud SCC** is ideal for organizations primarily using GCP, offering a centralized platform for managing security and compliance within the GCP ecosystem. * **Prowler** excels in multi-cloud environments, offering flexibility and comprehensive security checks across AWS, Azure, GCP, and Kubernetes without being confined to a single cloud provider. ### Setup and Flexibility * **GCP Cloud SCC** requires enabling various GCP services and may involve more complex setup, especially for multi-region or multi-account scenarios within GCP. * **Prowler** requires minimal setup and can be deployed quickly across different cloud environments, offering a more straightforward approach to multi-cloud security management. ### Customization and Compliance * **GCP Cloud SCC** provides predefined compliance checks within the GCP environment but may require additional tools or customization for broader or more specific requirements. * **Prowler** allows for extensive customization of security checks, compliance frameworks, and reporting, providing a flexible solution that can be tailored to an organization’s specific needs across various cloud platforms. ### Cost Efficiency * **GCP Cloud SCC** costs can scale with the volume of data processed and the number of enabled services, which may be significant in large or complex environments. SCC pricing is confusing to understand, and starts at \$0.071 per vCPU hour for some tiers and depending on the scan service. Take a look at the pricing model [here](https://cloud.google.com/security-command-center/pricing), godspeed. * **Prowler** helps manage costs by allowing selective reporting, such as sending only failed findings to SIEMs, and storing results in cost-effective ways, such as local storage or cloud buckets. Prowler is always \$0.001 per resource per day - no per account charge. ### Multi-Cloud and Multi-Region Support * **GCP Cloud SCC** is focused on GCP and may require additional tools for comprehensive multi-cloud support. * **Prowler** is inherently multi-cloud, supporting AWS, Azure, GCP, and Kubernetes out of the box, making it an ideal choice for organizations with diverse cloud footprints. ## Conclusion For a CISO evaluating these tools, the decision between GCP Cloud Security Command Center (Cloud SCC) and Prowler hinges on the organization’s cloud strategy, security management needs, and the level of flexibility and multi-cloud support required: * If the organization is heavily invested in GCP and needs a centralized platform that integrates seamlessly with GCP services for asset management, threat detection, and compliance monitoring, **GCP Cloud SCC** is likely the better choice. * If the organization operates in a multi-cloud environment or requires a highly customizable tool for performing detailed security assessments across AWS, Azure, GCP, and Kubernetes, **Prowler** offers a more flexible and cost-effective solution, especially for those needing quick deployment, minimal setup, and the ability to manage security across diverse cloud environments. # Comparison Source: https://docs.prowler.com/getting-started/comparison/index Click to learn more about each cloud security provider and learn how Prowler is differentiated. * [AWS Security Hub](/getting-started/comparison/awssecurityhub) * [Microsoft Sentinel](/getting-started/comparison/microsoftsentinel) * [Microsoft Defender](/getting-started/comparison/microsoftdefender) * [Google Cloud Security Command Center](/getting-started/comparison/gcp) # Microsoft Defender for Cloud Source: https://docs.prowler.com/getting-started/comparison/microsoftdefender **Use open-source scanning to validate and extend Microsoft Defender for Cloud** *** ## Overview If you're using Microsoft Defender for Cloud to monitor your Azure infrastructure, Prowler can complement it with fully transparent, customizable scans across Azure, AWS, GCP, and Kubernetes. Prowler helps you validate policies, automate compliance, and gain deeper visibility—all from the CLI, API or our Prowler UI. You can run Prowler alongside Defender for Cloud to: * Double-check security posture with open-source checks. * Customize rules for your organization’s policies. * Bring your own, or community contributed policies. * Automate multi-cloud scans in CI/CD or scheduled jobs. *** ## Why Use Prowler with Defender for Cloud Microsoft Defender for Cloud offers centralized dashboards, alerting, and some cross-cloud coverage. Prowler provides full transparency and control over what’s being checked and how those checks work—no vendor lock-in, no surprises. Use them together to get: * More confidence in your security posture * Checks you can inspect, modify, and version * CLI-first, portable scanning across clouds * Open-source tooling that integrates easily into pipelines and audits *** ## Quickstart Here’s how to install Prowler and run a scan in your Azure account. ### 1. Install Prowler ``` git clone https://github.com/prowler-cloud/prowler cd prowler ./install.sh ``` ### 2. Authenticate with Azure Make sure you're signed in and select your subscription: ``` az login export AZURE_SUBSCRIPTION_ID=$(az account show --query id -o tsv) ``` ### 3. Run a Scan ``` ./prowler -p Azure -f az-aks -f az-general ``` This will run checks focused on Azure Kubernetes Service (AKS) and general Azure best practices. ### 4. Review Results ``` cat output/prowler-output-*.json open output/prowler-output-*.html ``` You can export findings in JSON, CSV, JUnit, HTML, or AWS Security Hub–compatible formats. *** ## Compare Capabilities | Feature | Microsoft Defender for Cloud | Prowler | | - | - | - | | Azure-native posture management | ✅ | ✅ | | AWS, GCP, and Kubernetes support | ⚠️ (limited) | ✅ | | Custom policy creation | ❌ | ✅ | | CLI-first, scriptable | ❌ | ✅ | | Open source | ❌ | ✅ | | Compliance mappings (CIS, NIST, etc.) | ✅ (limited control) | ✅ (customizable) | | Exportable detections | ❌ | ✅ | *** ## Common Use Cases **✅ Validate policies** Run Prowler to confirm your Azure policies are configured as expected and compliant with frameworks like CIS or NIST. **✅ Automate compliance scans** Schedule regular Prowler scans in your CI/CD pipeline or infrastructure monitoring workflows. Generate reports for auditors or internal reviews. **✅ Extend detection coverage** If Defender for Cloud doesn’t cover all the services or resources in your environment, Prowler’s checks fill in the gaps. **✅ Build custom checks** Security is never one-size-fits-all. Prowler lets you write your own checks for organization-specific policies. # Microsoft Sentinel Source: https://docs.prowler.com/getting-started/comparison/microsoftsentinel Microsoft Sentinel is a scalable, cloud-native security information and event management (SIEM) and security orchestration automated response (SOAR) solution. It's designed to collect, detect, investigate, and respond to threats across the enterprise, primarily within the Azure cloud environment but also extending to on-premises and other cloud environments through various connectors. ## Key Features and Strengths * **SIEM and SOAR Capabilities:** Microsoft Sentinel combines SIEM and SOAR functionalities, allowing it to collect and analyze large volumes of data from various sources and automate responses to detected threats. * **Native Azure Integration:** As part of the Azure ecosystem, Sentinel integrates seamlessly with Azure services, providing deep visibility and analytics for Azure resources. * **Advanced Threat Detection:** Sentinel uses AI and machine learning to detect potential threats and anomalous activities, leveraging Microsoft's extensive threat intelligence network. * **Scalability and Flexibility:** Being cloud-native, Sentinel scales automatically to handle increasing data volumes and complexity without requiring extensive infrastructure management. * **Customizable Dashboards and Analytics:** Sentinel offers customizable dashboards and analytics, allowing security teams to tailor their views and queries to specific needs. * **Multi-Source Data Ingestion:** While focused on Azure, Sentinel can ingest data from multiple sources, including AWS, GCP, on-premises environments, and third-party security products. ## Limitations * **Azure-Centric:** While it supports multi-cloud environments, its primary focus and strengths are within the Azure ecosystem. Integration with other cloud platforms and on-premises environments may require additional connectors and configurations. * **Cost Considerations:** As a SIEM tool, Sentinel can become expensive, particularly as data ingestion and analysis volumes grow. The cost model is based on data volume, which can add up quickly in large environments. * **Complexity in Customization:** Although Sentinel offers advanced customization, setting up and fine-tuning these customizations can require significant expertise and effort, particularly in multi-cloud environments. ## Prowler Prowler is an open-source, multi-cloud security tool that offers extensive flexibility and customization, making it ideal for organizations that need to maintain a strong security posture across diverse cloud environments. Here are the key advantages of Prowler, particularly when compared to Microsoft Sentinel: ## Main Advantages of Prowler * **Multi-Region and Multi-Account Scanning by Default:** * Prowler is inherently multi-region and multi-account, requiring no additional configuration to scan across these environments. This capability is available out of the box without needing to enable specific services or create complex setups. * **Minimal Setup Requirements:** * Prowler requires only a role with appropriate permissions to begin scanning. There’s no need for extensive setup, making it easier and quicker to deploy across various environments. * **Versatile Execution Environment:** * Prowler can be run from a local workstation, container, AWS CloudShell, or even from other cloud providers like Azure or GCP by assuming a role. This versatility allows security teams to integrate Prowler into a wide range of operational workflows without being tied to a single cloud environment. * **Flexible Results Storage and Sharing:** * Prowler results can be stored directly into an S3 bucket, allowing for quick analysis or locally for easy sharing and collaboration. This flexibility is particularly useful for multi-cloud security assessments and incident response. * **Customizable Reporting and Analysis:** * Prowler supports exporting results in multiple formats, including JSON, CSV, OCSF format, and static HTML reports. Additionally, it can integrate with Amazon QuickSight for advanced analytics, and offers a SaaS model with resource-based pricing, making it adaptable to various organizational needs. * **SIEM Integration and Cost Efficiency:** * While Microsoft Sentinel has a built-in SIEM functionality, Prowler can send results directly into SIEM systems, including Microsoft Sentinel. By sending only failed findings, Prowler can help optimize costs associated with data ingestion and storage in SIEM platforms. * **Custom Checks and Compliance Frameworks:** * Prowler enables users to write custom checks, remediations, and compliance frameworks quickly, allowing organizations to adapt the tool to their specific security policies and regulatory requirements. * **Extensive Compliance Support:** * Prowler supports over 27 compliance frameworks out of the box, providing comprehensive coverage for AWS environments, which can be extended to multi-cloud scenarios. * **Kubernetes and Multi-Cloud Support:** * Prowler is designed to support security assessments beyond AWS, including Kubernetes clusters (including EKS) and environments in Azure and GCP. This capability is critical for organizations that operate across multiple cloud platforms and require consistent security posture management. * **All-Region Checks:** * Prowler runs all checks in all regions by default, ensuring comprehensive coverage without the limitations that may be imposed by region-specific configurations or services. ## Comparison Summary ### Scope and Environment * **Microsoft Sentinel** is an advanced SIEM/SOAR tool optimized for Azure environments, with support for multi-cloud and on-premises systems through connectors. * **Prowler** is a flexible, multi-cloud security tool that excels in environments where organizations need to manage security across AWS, Azure, GCP, and Kubernetes with minimal setup and high customizability. ### Setup and Flexibility * **Microsoft Sentinel** requires more setup, especially when integrating with non-Azure environments, and its cost scales with data ingestion. * **Prowler** requires minimal setup and can be easily deployed in any cloud or on-premises environment. Its ability to run from various environments and store results in flexible formats makes it particularly adaptable. ### Customization and Compliance * **Microsoft Sentinel** offers powerful but complex customization options, primarily within the Azure ecosystem. * **Prowler** provides straightforward customization of security checks, remediation actions, and compliance frameworks, with broad support for multiple compliance standards out of the box. ### Cost Efficiency * **Microsoft Sentinel** can become costly as data volumes grow, particularly in large or multi-cloud environments. * **Prowler** helps control costs by enabling selective reporting (e.g., sending only failed findings to SIEMs like Sentinel) and storing results in cost-effective ways, such as S3 or locally. ### Multi-Cloud and Multi-Region Support * **Microsoft Sentinel** supports multi-cloud environments but may require additional configuration and connectors. * **Prowler** is designed for multi-cloud environments from the ground up, with inherent support for AWS, Azure, GCP, Kubernetes, and all regions, making it an ideal tool for organizations with diverse cloud footprints. ## Conclusion For a CISO or security professional evaluating these tools, the decision between Microsoft Sentinel and Prowler hinges on the organization's cloud strategy, SIEM needs, and the level of customization and flexibility required: * If the organization is heavily invested in Azure and needs an integrated SIEM/SOAR solution with advanced threat detection, analytics, and automation capabilities, **Microsoft Sentinel** is likely the better choice. * If the organization operates in a multi-cloud environment or requires a highly customizable tool for performing detailed security assessments across AWS, Azure, GCP, and Kubernetes, **Prowler** offers a more flexible and cost-effective solution, especially for those needing quick deployment, minimal setup, and the ability to manage security across diverse cloud environments. # Prowler API Reference Source: https://docs.prowler.com/getting-started/goto/prowler-api-reference # Go to Cloud Source: https://docs.prowler.com/getting-started/goto/prowler-cloud # Go to Hub Source: https://docs.prowler.com/getting-started/goto/prowler-hub # Installation Source: https://docs.prowler.com/getting-started/installation/prowler-app > [!TIP] > > [Prowler Cloud](https://cloud.prowler.com/sign-up) runs the same application with no installation or maintenance. Follow the [Prowler Cloud guide](/user-guide/tutorials/prowler-app) to start scanning right away. ### Installation Prowler Local Server offers flexible installation methods tailored to various environments. Refer to the [Prowler Cloud guide](/user-guide/tutorials/prowler-app) for detailed usage instructions, which apply to Prowler Local Server as well. > [!WARNING] > > Prowler configuration is based on `.env` files. Every version of Prowler can have differences on that file, so, please, use the file that corresponds with that version or repository branch or tag. > [tab] Docker Compose > > *Requirements*: > > * `Docker Compose` installed: [https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/). > > *Commands*: > > ```bash macOS/Linux theme={null} > VERSION=$(curl -s https://api.github.com/repos/prowler-cloud/prowler/releases/latest | jq -r .tag_name) > curl -sLO "https://raw.githubusercontent.com/prowler-cloud/prowler/refs/tags/${VERSION}/docker-compose.yml" > # Environment variables can be customized in the .env file. Using default values in production environments is not recommended. > curl -sLO "https://raw.githubusercontent.com/prowler-cloud/prowler/refs/tags/${VERSION}/.env" > docker compose up -d > ``` > > ```powershell Windows PowerShell theme={null} > $VERSION = (Invoke-RestMethod -Uri "https://api.github.com/repos/prowler-cloud/prowler/releases/latest").tag_name > Invoke-WebRequest -Uri "https://raw.githubusercontent.com/prowler-cloud/prowler/refs/tags/$VERSION/docker-compose.yml" -OutFile "docker-compose.yml" > # Environment variables can be customized in the .env file. Using default values in production environments is not recommended. > Invoke-WebRequest -Uri "https://raw.githubusercontent.com/prowler-cloud/prowler/refs/tags/$VERSION/.env" -OutFile ".env" > docker compose up -d > ``` > > For a secure setup, the API auto-generates a unique key pair, `DJANGO_TOKEN_SIGNING_KEY` and `DJANGO_TOKEN_VERIFYING_KEY`, and stores it in `~/.config/prowler-api` (non-container) or the bound Docker volume in `_data/api` (container). Never commit or reuse static/default keys. To rotate keys, delete the stored key files and restart the API. > [tab] GitHub > > *Requirements*: > > * `git` installed. > > * `uv` installed: [uv installation](https://docs.astral.sh/uv/getting-started/installation/). > > * `pnpm` installed through [Corepack](https://pnpm.io/installation#using-corepack) or the standalone [pnpm installation](https://pnpm.io/installation). > > * `Docker Compose` installed: [https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/). > > > [!WARNING] > > > > Make sure to have `api/.env` and `ui/.env.local` files with the required environment variables. You can find the required environment variables in the [`api/.env.template`](https://github.com/prowler-cloud/prowler/blob/master/api/.env.example) and [`ui/.env.template`](https://github.com/prowler-cloud/prowler/blob/master/ui/.env.template) files. > > *Commands to run the API*: > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler \ > cd prowler/api \ > uv sync \ > source .venv/bin/activate \ > set -a \ > source .env \ > docker compose up postgres valkey -d \ > cd src/backend \ > python manage.py migrate --database admin \ > gunicorn -c config/guniconf.py config.wsgi:application > ``` > > > Now, you can access the API documentation at [http://localhost:8080/api/v1/docs](http://localhost:8080/api/v1/docs). > > *Commands to run the API Worker*: > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler \ > cd prowler/api \ > uv sync \ > source .venv/bin/activate \ > set -a \ > source .env \ > cd src/backend \ > python -m celery -A config.celery worker -l info -E > ``` > > *Commands to run the API Scheduler*: > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler \ > cd prowler/api \ > uv sync \ > source .venv/bin/activate \ > set -a \ > source .env \ > cd src/backend \ > python -m celery -A config.celery beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler > ``` > > *Commands to run the UI*: > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler \ > cd prowler/ui \ > corepack enable \ > corepack install \ > pnpm install --frozen-lockfile \ > pnpm run build \ > pnpm start > ``` > > > Enjoy Prowler Local Server at [http://localhost:3000](http://localhost:3000) by signing up with your email and password. > > > [!WARNING] > > > > Google and GitHub authentication works out of the box in [Prowler Cloud](https://prowler.com). In Prowler Local Server it requires OAuth credentials: see [Social Login Configuration](/user-guide/tutorials/prowler-app-social-login). ### Updating Prowler Local Server Upgrade Prowler Local Server installation using one of two options: #### Option 1: Updating the Environment File To update the environment file: Edit the `.env` file and change version values: ```env theme={null} PROWLER_UI_VERSION="5.48.0" PROWLER_API_VERSION="5.48.0" ``` > [!NOTE] > > You can find the latest versions of Prowler Local Server in the [Releases GitHub section](https://github.com/prowler-cloud/prowler/releases) or in the [Container Versions](#container-versions) section of this documentation. #### Option 2: Using Docker Compose Pull ```bash theme={null} docker compose pull --policy always ``` The `--policy always` flag ensures that Docker pulls the latest images even if they already exist locally. > [!NOTE] > > **What Gets Preserved During Upgrade** > > Everything is preserved, nothing will be deleted after the update. ### Troubleshooting Installation Issues If containers don't start, check logs for errors: ```bash theme={null} # Check logs for errors docker compose logs # Verify image versions docker images | grep prowler ``` If issues are encountered, rollback to the previous version by changing the `.env` file back to the previous version and running: ```bash theme={null} docker compose pull docker compose up -d ``` ### Container Versions The available versions of Prowler Local Server are the following: * `latest`: in sync with `master` branch (please note that it is not a stable version) * `v4-latest`: in sync with `v4` branch (please note that it is not a stable version) * `v3-latest`: in sync with `v3` branch (please note that it is not a stable version) * `` (release): you can find the releases [here](https://github.com/prowler-cloud/prowler/releases), those are stable releases. * `stable`: this tag always points to the latest release. * `v4-stable`: this tag always points to the latest release for v4. * `v3-stable`: this tag always points to the latest release for v3. The container images are available here: * Prowler Local Server: * [DockerHub - Prowler UI](https://hub.docker.com/r/prowlercloud/prowler-ui/tags) * [DockerHub - Prowler API](https://hub.docker.com/r/prowlercloud/prowler-api/tags) # Installation Source: https://docs.prowler.com/getting-started/installation/prowler-cli ## Installation To install Prowler as a Python package, use `Python >= 3.10, <= 3.13`. Prowler is available as a project in [PyPI](https://pypi.org/project/prowler/): > [tab] pipx > > [pipx](https://pipx.pypa.io/stable/) installs Python applications in isolated environments. Use `pipx` for global installation. > > *Requirements*: > > * `Python >= 3.10, <= 3.13` > * `pipx` installed: [pipx installation](https://pipx.pypa.io/stable/installation/). > * AWS, GCP, Azure and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > pipx install prowler > prowler -v > ``` > [tab] pip > > > [!WARNING] > > > > This method modifies the chosen installation environment. Consider using [pipx](https://docs.prowler.com/projects/prowler-open-source/en/latest/#__tabbed_1_1) for global installation. > > *Requirements*: > > * `Python >= 3.10, <= 3.13` > * `Python pip >= 21.0.0` > * AWS, GCP, Azure, M365 and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > pip install prowler > prowler -v > ``` > [tab] Docker > > *Requirements*: > > * Have `docker` installed: [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/). > * In the command below, change `-v` to your local directory path to access the reports. > * AWS, GCP, Azure and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > docker run -ti --rm -v /your/local/dir/prowler-output:/home/prowler/output \ > --name prowler \ > --env AWS_ACCESS_KEY_ID \ > --env AWS_SECRET_ACCESS_KEY \ > --env AWS_SESSION_TOKEN toniblyx/prowler:latest > ``` > [tab] GitHub > > *Requirements for Developers*: > > * `git` > * `uv` installed: [uv installation](https://docs.astral.sh/uv/getting-started/installation/). > * AWS, GCP, Azure and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler > cd prowler > uv sync > uv run python prowler-cli.py -v > ``` > > > [!NOTE] > > > > If you want to clone Prowler from Windows, use `git config core.longpaths true` to allow long file paths. > [tab] Amazon Linux 2 > > *Requirements*: > > * `Python >= 3.10, <= 3.13` > * AWS, GCP, Azure and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > python3 -m pip install --user pipx > python3 -m pipx ensurepath > pipx install prowler > prowler -v > ``` > [tab] Ubuntu > > *Requirements*: > > * `Ubuntu 23.04` or above. For older Ubuntu versions, check [pipx installation](https://docs.prowler.com/projects/prowler-open-source/en/latest/#__tabbed_1_1) and ensure `Python >= 3.10, <= 3.13` is installed. > * `Python >= 3.10, <= 3.13` > * AWS, GCP, Azure and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > sudo apt update > sudo apt install pipx > pipx ensurepath > pipx install prowler > prowler -v > ``` > [tab] Brew > > *Requirements*: > > * `Brew` installed on Mac or Linux > * AWS, GCP, Azure and/or Kubernetes credentials > > *Commands*: > > ```bash theme={null} > brew install prowler > prowler -v > ``` > [tab] AWS CloudShell > > After the migration of AWS CloudShell from Amazon Linux 2 to Amazon Linux 2023 [\[1\]](https://aws.amazon.com/about-aws/whats-new/2023/12/aws-cloudshell-migrated-al2023/) [\[2\]](https://docs.aws.amazon.com/cloudshell/latest/userguide/cloudshell-AL2023-migration.html), there is no longer a need to manually compile Python 3.9 as it is already included in AL2023. Prowler can thus be easily installed following the generic method of installation via pip. Follow the steps below to successfully execute Prowler v4 in AWS CloudShell: > > *Requirements*: > > * Open AWS CloudShell `bash`. > > *Commands*: > > ```bash theme={null} > sudo bash > adduser prowler > su prowler > python3 -m pip install --user pipx > python3 -m pipx ensurepath > pipx install prowler > cd /tmp > prowler aws > ``` > > > [!NOTE] > > > > To download the results from AWS CloudShell, select Actions -> Download File and add the full path of each file. For the CSV file it will be something like `/tmp/output/prowler-output-123456789012-20221220191331.csv` > [tab] Azure CloudShell > > *Requirements*: > > * Open Azure CloudShell `bash`. > > *Commands*: > > ```bash theme={null} > python3 -m pip install --user pipx > python3 -m pipx ensurepath > pipx install prowler > cd /tmp > prowler azure --az-cli-auth > ``` ## Updating Prowler CLI Upgrade Prowler CLI to the latest release using the same method chosen for installation: > [tab] pipx > > ```bash theme={null} > pipx upgrade prowler > prowler -v > ``` > [tab] pip > > ```bash theme={null} > pip install --upgrade prowler > prowler -v > ``` > [tab] Docker > > Pull the desired image tag to fetch the latest version: > > ```bash theme={null} > docker pull toniblyx/prowler:latest > ``` > > > [!NOTE] > > > > Replace `latest` with a specific release tag (for example, `stable` or ``) to pin a version. Refer to the [Container Versions](#container-versions) section for the full list of available tags. > [tab] GitHub > > Pull the latest changes and sync the environment: > > ```bash theme={null} > cd prowler > git pull > uv sync > uv run python prowler-cli.py -v > ``` > > > [!NOTE] > > > > To upgrade to a specific release, check out the corresponding tag before syncing: `git checkout `. > [tab] Brew > > ```bash theme={null} > brew upgrade prowler > prowler -v > ``` > [tab] CloudShell > > Both AWS CloudShell and Azure CloudShell install Prowler with `pipx`, so the upgrade command is the same: > > ```bash theme={null} > pipx upgrade prowler > prowler -v > ``` > [!NOTE] > > To install a specific version instead of the latest release, pin it explicitly. For example, with `pipx`: `pipx install prowler==`, or with `pip`: `pip install prowler==`. The available releases are listed in the [Releases GitHub section](https://github.com/prowler-cloud/prowler/releases). ## Container Versions The available versions of Prowler CLI are the following: * `latest`: in sync with `master` branch (please note that it is not a stable version) * `v4-latest`: in sync with `v4` branch (please note that it is not a stable version) * `v3-latest`: in sync with `v3` branch (please note that it is not a stable version) * `` (release): you can find the releases [here](https://github.com/prowler-cloud/prowler/releases), those are stable releases. * `stable`: this tag always points to the latest release. * `v4-stable`: this tag always points to the latest release for v4. * `v3-stable`: this tag always points to the latest release for v3. The container images are available here: * Prowler CLI: * [DockerHub](https://hub.docker.com/r/toniblyx/prowler/tags) * [AWS Public ECR](https://gallery.ecr.aws/prowler-cloud/prowler) # Installation Source: https://docs.prowler.com/getting-started/installation/prowler-mcp There are **two ways** to use Prowler MCP Server: > [card] Cloud MCP Server (Recommended) > > **No installation required** - Just configuration > > Use `https://mcp.prowler.com/mcp` > [card] Local MCP Server > > **Local installation** - Full control > > Install via Docker, PyPI, or source code For the Cloud MCP Server, go directly to the [Configuration Guide](/getting-started/basic-usage/prowler-mcp#cloud-mcp-server-configuration-recommended) to set up your Claude Desktop, Cursor, or other MCP client. **This guide is focused on local installation, the Local MCP Server**. ## Installation Methods Choose one of the following installation methods: > [tab] Docker (Recommended) > > ### Pull from Docker Hub > > The easiest way to run locally is using the official Docker image: > > ```bash theme={null} > docker pull prowlercloud/prowler-mcp > ``` > > ### Run the Container > > ```bash theme={null} > # STDIO mode (for local MCP clients) > docker run --rm -i prowlercloud/prowler-mcp > > # HTTP mode (for remote access) > docker run --rm -p 8000:8000 \ > prowlercloud/prowler-mcp \ > --transport http --host 0.0.0.0 --port 8000 > ``` > > ### With Environment Variables > > ```bash theme={null} > docker run --rm -i \ > -e PROWLER_API_KEY="pk_your_api_key" \ > -e API_BASE_URL="https://api.prowler.com/api/v1" \ > prowlercloud/prowler-mcp > ``` > > > [!NOTE] > > > > **Docker Hub:** [prowlercloud/prowler-mcp](https://hub.docker.com/r/prowlercloud/prowler-mcp) > [tab] PyPI Package > > ### Install via pip > > > [!WARNING] > > > > **Coming Soon** - PyPI package will be available shortly > [tab] From Source (Development) > > ### Install uv > > If `uv` is not installed, install it first. Visit [uv documentation](https://docs.astral.sh/uv/) for more installation options. > > ### Clone the Repository > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler.git > cd prowler/mcp_server > ``` > > ### Install Dependencies > > The MCP server uses `uv` for dependency management. Install dependencies with: > > ```bash theme={null} > uv sync > ``` > > ### Verify Installation > > Test that the server is properly installed: > > ```bash theme={null} > uv run prowler-mcp --help > ``` > > The help message with available command-line options should appear. > > > [!NOTE] > > > > **For Development:** This method is recommended if you're developing or contributing to the MCP server. > [tab] Build Docker Image > > ### Prerequisites > > Ensure Docker is installed on your system. Visit [Docker documentation](https://docs.docker.com/get-docker/) for more installation options. > > ### Clone the Repository > > ```bash theme={null} > git clone https://github.com/prowler-cloud/prowler.git > cd prowler/mcp_server > ``` > > ### Build the Docker Image > > ```bash theme={null} > docker build -t prowler-mcp . > ``` > > This creates a Docker image named `prowler-mcp` with all necessary dependencies. > > ### Verify Installation > > Test that the Docker image was built successfully: > > ```bash theme={null} > docker run --rm prowler-mcp --help > ``` > > The help message with available command-line options should appear. *** ## Updating Prowler MCP Server When running the Local MCP Server, upgrade to the latest version using the same method chosen for installation. The Cloud MCP Server (`https://mcp.prowler.com/mcp`) is always kept up to date by Prowler and requires no action. > [tab] Docker > > Pull the latest image and restart the container: > > ```bash theme={null} > docker pull prowlercloud/prowler-mcp > ``` > > > [!NOTE] > > > > Recreate any running container after pulling the new image so the updated version takes effect. > [tab] From Source > > Pull the latest changes and sync the dependencies: > > ```bash theme={null} > cd prowler/mcp_server > git pull > uv sync > uv run prowler-mcp --help > ``` > [tab] Build Docker Image > > Pull the latest source and rebuild the image: > > ```bash theme={null} > cd prowler/mcp_server > git pull > docker build -t prowler-mcp . > ``` *** ## Command Line Options The Prowler MCP Server supports the following command-line arguments: ```bash theme={null} prowler-mcp [--transport {stdio,http}] [--host HOST] [--port PORT] ``` | Argument | Values | Default | Description | | - | - | - | - | | `--transport` | `stdio`, `http` | `stdio` | Transport method for MCP communication | | `--host` | Any valid hostname/IP | `127.0.0.1` | Host to bind to (HTTP mode only) | | `--port` | Port number | `8000` | Port to bind to (HTTP mode only) | ### Examples ```bash theme={null} # Default STDIO mode for local MCP client integration prowler-mcp # Explicit STDIO mode prowler-mcp --transport stdio # HTTP mode on default host and port (127.0.0.1:8000) prowler-mcp --transport http # HTTP mode accessible from any network interface prowler-mcp --transport http --host 0.0.0.0 # HTTP mode with custom port prowler-mcp --transport http --host 0.0.0.0 --port 8080 ``` ## Environment Variables Configure the server using environment variables: | Variable | Description | Required | Default | | - | - | - | - | | `PROWLER_API_KEY` | Prowler API key | Only for STDIO mode | - | | `API_BASE_URL` | Custom Prowler API endpoint | No | `https://api.prowler.com/api/v1` | | `PROWLER_MCP_TRANSPORT_MODE` | Default transport mode (overwritten by `--transport` argument) | No | `stdio` | ```bash macOS/Linux theme={null} export PROWLER_API_KEY="pk_your_api_key_here" export API_BASE_URL="https://api.prowler.com/api/v1" export PROWLER_MCP_TRANSPORT_MODE="http" ``` ```bash Windows PowerShell theme={null} $env:PROWLER_API_KEY="pk_your_api_key_here" $env:API_BASE_URL="https://api.prowler.com/api/v1" $env:PROWLER_MCP_TRANSPORT_MODE="http" ``` > [!WARNING] > > Never commit your API key to version control. Use environment variables or secure secret management solutions. ### Using Environment Files For convenience, create a `.env` file in the `mcp_server` directory: ```bash .env theme={null} PROWLER_API_KEY=pk_your_api_key_here API_BASE_URL=https://api.prowler.com/api/v1 PROWLER_MCP_TRANSPORT_MODE=stdio ``` When using Docker, pass the environment file: ```bash theme={null} docker run --rm --env-file .env -it prowler-mcp ``` ## Running from Any Location Run the MCP server from anywhere using `uvx`: ```bash theme={null} uvx /path/to/prowler/mcp_server/ ``` This is particularly useful when configuring MCP clients that need to launch the server from a specific path. ## Production Deployment For production deployments that require customization, it is recommended to use the ASGI application that can be found in `prowler_mcp_server.server`. This can be run with uvicorn: ```bash theme={null} uvicorn prowler_mcp_server.server:app --host 0.0.0.0 --port 8000 ``` For more details on production deployment options, see the [FastMCP production deployment guide](https://gofastmcp.com/deployment/http#production-deployment) and [uvicorn settings](https://www.uvicorn.org/settings/). ### Entrypoint Script The source tree includes `entrypoint.sh` to simplify switching between the standard CLI runner and the ASGI app. The first argument selects the mode and any additional flags are passed straight through: ```bash theme={null} # Default CLI experience (prowler-mcp console script) ./entrypoint.sh main --transport http --host 0.0.0.0 # ASGI app via uvicorn ./entrypoint.sh uvicorn --host 0.0.0.0 --port 9000 ``` Omitting the mode defaults to `main`, matching the `prowler-mcp` console script. When `uvicorn` mode is selected, the script exports `PROWLER_MCP_TRANSPORT_MODE=http` automatically. This is the default entrypoint for the Docker container. ## Next Steps Now that you have the Prowler MCP Server installed, proceed to configure your MCP client: > [card] [Configuration](/getting-started/basic-usage/prowler-mcp) > > Configure Claude Desktop, Cursor, or other MCP clients ## Getting Help If you encounter issues during installation: * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Prowler Product Families Source: https://docs.prowler.com/getting-started/products/index Official names for Prowler Open Source projects and Prowler Products, including former product names. Prowler ships two product families: Prowler Products, operated or licensed by the Prowler team, and Open Source projects, free to run and extend. This page is the reference for every official name. If a page or blog post uses a former name, the [Former Names](#former-names) table maps it to the current one. > [!NOTE] > > Read the [public announcement of the Prowler product families](https://prowler-workspace.slack.com/archives/C03JUQVM33L/p1784120677833319) in our Slack community. ## Prowler Products | Name | Description | | - | - | | [Prowler Cloud](/getting-started/products/prowler-cloud) | Managed cloud security platform operated by the Prowler team. See [pricing](https://prowler.com/pricing). | | Prowler Private Cloud | Prowler Cloud deployed in your own environment. Formerly Prowler Enterprise. Available [on AWS Marketplace](/getting-started/products/prowler-private-cloud-aws-marketplace). See [pricing](https://prowler.com/pricing). | | [Prowler Hub](https://hub.prowler.com) | Free public library of versioned checks, cloud service artifacts, and compliance frameworks. | | [Prowler Lighthouse AI](/getting-started/products/prowler-cloud-lighthouse) | AI security analyst capabilities within Prowler Cloud and Prowler Private Cloud. | | [Prowler MCP](/getting-started/products/prowler-mcp) | MCP server that connects AI assistants and agents to Prowler, including IDE plugins such as [Prowler for Claude Code](/user-guide/ai-agents/claude-code). | > [!NOTE] > > Throughout this documentation, the green cloud icon in the sidebar marks sections and pages for capabilities that require a Prowler Cloud or Prowler Private Cloud [subscription](https://prowler.com/pricing). Products without a documentation page here are available through the Prowler team. [Contact us](https://prowler.com/contact) for details. ## Open Source Projects | Name | Description | | - | - | | [Prowler CLI](/getting-started/products/prowler-cli) | Command line tool to run security scans across all supported providers. | | [Prowler Local Server](/getting-started/products/prowler-app) | Self-hosted web application and API to run scans, visualize findings, and manage cloud providers. Formerly Prowler App. | | [Prowler Local Dashboard](/user-guide/cli/tutorials/dashboard) | Local web dashboard to visualize scan results from Prowler CLI CSV outputs. Shipped with Prowler CLI. | | [Prowler SDK](/getting-started/products/prowler-sdk) | Python library that powers Prowler CLI and Prowler Local Server. Part of the [prowler repository](https://github.com/prowler-cloud/prowler). | ## Former Names | Former name | Current name | | - | - | | Prowler App | [Prowler Local Server](/getting-started/products/prowler-app) | | Prowler Enterprise | Prowler Private Cloud | ## Prowler for MSPs and MSSPs Prowler partners with managed service providers (MSPs) and managed security service providers (MSSPs) that operate Prowler for their customers. Visit [partners.prowler.com](https://partners.prowler.com) to become a partner. # Overview Source: https://docs.prowler.com/getting-started/products/prowler-app Prowler Local Server is a self-hosted web application that simplifies running Prowler. It is the open source counterpart of [Prowler Cloud](/getting-started/products/prowler-cloud), which runs the same application as a managed service. It provides: * **User-friendly interface** for configuring and executing scans * Dashboard to **view results** and manage **security findings** ![Prowler Local Server](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/products/overview.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=96ceafb0329e6aec90333fa492da83af) ## Components Prowler Local Server consists of four main components: * **Prowler UI**: User-friendly web interface for running Prowler and viewing results, powered by Next.js * **Prowler API**: Backend API that executes Prowler scans and stores results, built with Django REST Framework * **Prowler SDK**: Python SDK that integrates with Prowler CLI for advanced functionality * **Prowler MCP Server**: Model Context Protocol server that exposes AI tools for Lighthouse, the AI-powered security assistant. Required dependency for Lighthouse. Supporting infrastructure includes: * **PostgreSQL**: Persistent storage of scan results * **Celery Workers**: Asynchronous execution of Prowler scans * **Celery Beat (API Scheduler)**: Schedules recurring scans and enqueues jobs on the broker * **Valkey**: In-memory database serving as message broker for Celery workers * **Neo4j**: Graph database used by the Attack Paths feature to combine cloud inventory with Prowler findings (currently populated by AWS scans) ```mermaid theme={null} flowchart TB user([User / Security Team]) cli([Prowler CLI]) subgraph APP["Prowler Local Server"] ui["Prowler UI
(Next.js)"] api["Prowler API
(Django REST Framework)"] worker["API Worker
(Celery)"] beat["API Scheduler
(Celery Beat)"] mcp["Prowler MCP Server
(Lighthouse AI tools)"] end sdk["Prowler SDK
(Python)"] subgraph DATA["Data Layer"] pg[("PostgreSQL")] valkey[("Valkey / Redis")] neo4j[("Neo4j")] end providers["Providers"] user --> ui user --> cli ui -->|REST| api ui -->|MCP HTTP| mcp mcp -->|REST| api api --> pg api --> valkey beat -->|enqueue jobs| valkey valkey -->|dispatch| worker worker --> pg worker -->|Attack Paths| neo4j worker -->|invokes| sdk cli --> sdk sdk --> providers ``` # Overview Source: https://docs.prowler.com/getting-started/products/prowler-cli Prowler CLI is a command-line interface for running Prowler scans from the terminal. ```console theme={null} prowler ``` ![Prowler CLI Execution](https://mintcdn.com/prowler/9AoCN7Q_gXN7wF7l/images/short-display.png?fit=max\&auto=format\&n=9AoCN7Q_gXN7wF7l\&q=85\&s=ad991dd5d9346068631cd7b328b04408) ## Prowler Local Dashboard ```console theme={null} prowler dashboard ``` ![Prowler Local Dashboard](https://mintcdn.com/prowler/LI3palQgXkn4dRXg/images/products/dashboard.png?fit=max\&auto=format\&n=LI3palQgXkn4dRXg\&q=85\&s=02a45f64c2394399fa1a44a36fc6897d) Prowler includes hundreds of security controls aligned with widely recognized industry frameworks and standards, including: * CIS Benchmarks (AWS, Azure, Microsoft 365, Kubernetes, GitHub) * NIST SP 800-53 (rev. 4 and 5) and NIST SP 800-171 * NIST Cybersecurity Framework (CSF) * CISA Guidelines * FedRAMP Low & Moderate * PCI DSS v3.2.1 and v4.0 * ISO/IEC 27001:2013 and 2022 * SOC 2 * GDPR (General Data Protection Regulation) * HIPAA (Health Insurance Portability and Accountability Act) * FFIEC (Federal Financial Institutions Examination Council) * ENS RD2022 (Spanish National Security Framework) * GxP 21 CFR Part 11 and EU Annex 11 * RBI Cybersecurity Framework (Reserve Bank of India) * KISA ISMS-P (Korean Information Security Management System) * MITRE ATT\&CK * AWS Well-Architected Framework (Security & Reliability Pillars) * AWS Foundational Technical Review (FTR) * Microsoft NIS2 Directive (EU) * Custom threat scoring frameworks (prowler\_threatscore) * Custom security frameworks for enterprise needs # Overview Source: https://docs.prowler.com/getting-started/products/prowler-cloud [Prowler Cloud](https://prowler.com) makes Cloud Security easy and enables your team to build trust in their deployed services and applications. Prowler Cloud automates scanning single or multiple accounts and has all of the benefits of Prowler Open Source, plus hands-off continuous monitoring, auto-scaling workers for faster execution, integrations, personalized support options and out of the box social authentication. ![](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/products/overview.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=96ceafb0329e6aec90333fa492da83af) > [card] [Create your account here to see Prowler Cloud in action](https://cloud.prowler.com/sign-up) With 100% consistency across our open source policies and APIs. Prowler Cloud provides the following added benefits:
  • Immediate sign-up and account provisioning, including a trial period with zero billing details needed at registration.
  • Simple, transparent pricing, with cloud account sizing and exact pricing being available to view in your account settings.
  • SOC2 Security processes around the deployment, management, data protection and security updates of your prowler environment.
  • Helpers for smooth onboarding of cloud environments (Eg. Automatic account ID and ExternalID for AWS assumed roles, Known Static IP for Kubernetes access).
  • Zero touch third party notifications to Slack, Jira, and more.
The team who built [Prowler](https://github.com/prowler-cloud/prowler), has helped thousands of companies get Cloud Security under control, is now making it easier by taking [Prowler](https://github.com/prowler-cloud/prowler) to the [Cloud](https://prowler.com)! # AWS Marketplace Source: https://docs.prowler.com/getting-started/products/prowler-cloud-aws-marketplace This page explains how to subscribe to **Prowler Cloud** through the **AWS Marketplace**, how to activate the subscription in Prowler Cloud, how billing works, and how to fix the errors you may hit on the way. ## Plans Prowler Cloud has two listings in the AWS Marketplace. Both give you the same product. They differ in how you commit and how you pay. A **provider** is a cloud account you connect to Prowler Cloud: an AWS account, an Azure subscription, a GCP project, a Kubernetes cluster, and so on. | | Monthly (pay as you go) | Annual (billed annually) | | - | - | - | | Listing | [Prowler Cloud \$99/provider per month (Pay as You Go)](https://aws.amazon.com/marketplace/pp/prodview-nmbvelz746oyk) | [Prowler Cloud \$79/provider per month (Billed Annually)](https://aws.amazon.com/marketplace/pp/prodview-wwehsmzui25ri) | | Billing | Monthly, per connected provider | Once, at checkout, for the full 12 months | | Commitment | None. Cancel anytime. | 12 months for the number of providers you choose during checkout on AWS. | | Resources beyond the included amount | Billed per resource | Billed per resource, at the annual rate | | Providers beyond your commitment | Not applicable | Billed monthly at the pay-as-you-go rate | For prices, included resources and per-resource rates, see the [Prowler Cloud pricing page](https://prowler.com/pricing/). ## Before You Subscribe * **One AWS account pays for the whole organization.** Subscribe from a single AWS account. You then connect as many providers as you need, from any cloud, inside Prowler Cloud. You do not subscribe again for each AWS account you scan. * **Decide which Prowler Cloud organization will pay.** Activation links the AWS purchase to the organization you are signed in to. If you belong to several organizations, switch to the right one before you activate. See [Activate the Subscription in Prowler Cloud](#activate-the-subscription-in-prowler-cloud). * **Annual plan: decide the provider count first.** AWS asks for it during checkout, and AWS charges the full year at that moment. Providers you add beyond that count are billed monthly at the pay-as-you-go rate. AWS may not let you cancel an annual contract yourself from the console. See [Cancel the Subscription](#cancel-the-subscription) before you commit. * **Cancel any card-billed subscription first.** An organization already billed by credit card cannot switch to AWS Marketplace billing until that subscription is cancelled. This prevents double charges. ## Subscribe on AWS Marketplace **1. Open the listing** Sign in to the AWS account that will pay, open the listing for the plan you want, and click **View purchase options**. > [tab] Monthly > > Open [Prowler Cloud \$99/provider per month (Pay as You Go)](https://aws.amazon.com/marketplace/pp/prodview-nmbvelz746oyk). > > ![Monthly Prowler Cloud listing on AWS Marketplace with the View purchase options button highlighted](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/listing-monthly.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=34191058a8db35c0294ed90b83dffc0d) > [tab] Annual > > Open [Prowler Cloud \$79/provider per month (Billed Annually)](https://aws.amazon.com/marketplace/pp/prodview-wwehsmzui25ri). > > ![Annual Prowler Cloud listing on AWS Marketplace with the View purchase options button highlighted](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/listing-annual.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=c1888d2a9dea83b4330b252fe8bdeee9) **2. Review the purchase and subscribe** > [tab] Monthly > > Scroll to **Purchase details** and click **Subscribe**. There is no upfront charge. AWS bills your usage at the end of each month. > > ![Purchase details for the monthly listing with the Subscribe button highlighted](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/purchase-monthly.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=3e654fd5020a0252328ca7febffb63ac) > [tab] Annual > > Under **Pricing details**, select the **providers** dimension and enter the **Number of units**. One unit is one provider for the 12-month term. Review the **Contract total**, then click **Subscribe** at the bottom of the page. AWS charges the full year now. > > ![Purchase options for the annual listing showing the contract details, the providers dimension and the Number of units table](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/purchase-annual.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=5a66fd3bd4a5d505daef75f2c24a5564) > > **Auto-renewal** is on by default. Leave it on to have AWS renew the contract for another 12 months at the end date, or choose **Do not automatically renew this contract**. You can change this from **Manage subscriptions** any time before the renewal date. **3. Click Set up your account** AWS confirms the purchase and shows a **Set up your account** button. Click it. AWS sends your browser to Prowler Cloud with a setup link. ![AWS Marketplace purchase confirmation banner with the Set up your account button](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/set-up-your-account.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=95b7dbab1f2db28ff1295b2ad5cb9d74) > [!NOTE] > > The setup link expires quickly: AWS documents roughly one hour, and never more than four. If the link expires, you close the tab, or need to start over, return to [Manage subscriptions](https://console.aws.amazon.com/marketplace/subscriptions) in the AWS Marketplace console, open **Prowler Cloud**, and click **Set up your account** again to get a fresh link. ## Activate the Subscription in Prowler Cloud Nothing is linked until you confirm it in Prowler Cloud. The purchase is safe on the AWS side while you complete these steps. **1. Sign in or create your account** Prowler Cloud shows the sign-in page with a banner that reads "To finish setting up your AWS Marketplace subscription, sign in or register if you don't have an account yet." ![Prowler Cloud sign-in page with the AWS Marketplace banner](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/sign-in-marketplace.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=a6c9fe621e6a0bf3f110a8dbf54b1ec5) If you do not have an account yet, click **Sign up**. The purchase carries over once you sign in with the new account. ![Prowler Cloud sign-up page with the AWS Marketplace banner](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/sign-up-marketplace.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=8269ba73a95b75bd4a18d502daf8c89e) **2. Check the organization and activate** The billing page shows a card titled **Activate your AWS Marketplace subscription**. It names the organization the purchase will be linked to. ![Activation card naming the organization, with the Activate subscription button and the Continue to billing without activating link](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/activate-confirm.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=24e2da4afa6972f4fbeaf441a785f749) > [!WARNING] > > Read the organization name before you click. Activation is a billing decision: charges for that organization go to the AWS account you subscribed with. If it is not the organization you want to pay for, switch organizations first, then come back to the billing page. Click **Activate subscription**. Prowler Cloud links the purchase and activates the subscription. Two short status messages appear while it works: "Linking your AWS Marketplace purchase…" and "Activating your subscription…". ![Activation card showing the Activating your subscription progress message](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/activate-working.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=8450a591fa2b19307fcc15be330bf015) **Continue to billing without activating** discards the setup link and leaves the organization unchanged. Use it only if you landed in the wrong organization. To activate later, get a fresh link from the AWS Marketplace console as described above. **3. Confirm the subscription is active** The billing page now states that you subscribed through AWS Marketplace, shows the AWS account that pays, and links to your subscription in the AWS Marketplace console. ![Prowler Cloud billing page for an AWS Marketplace subscription, showing the paying AWS account and the link to the AWS Marketplace console](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/billing-subscribed.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=7f0a5746108cddf55c2f14737d891a7d) There is no payment method, invoice history, or cancel button on this page. AWS handles all of that. If something goes wrong during activation, see [Activation errors](#activation-errors). ## After Activation * Add providers from the **Providers** page in Prowler Cloud. Every provider you add is covered by the same AWS subscription, whatever cloud it belongs to. * All charges come from AWS. Find them under **Amazon Web Services, Inc. - Marketplace** in [AWS Billing](https://console.aws.amazon.com/billing/home#/bills). ![AWS Billing page showing the Amazon Web Services, Inc. - Marketplace line](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/aws-marketplace/marketplace-billing.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=813d7f1db7b1dc8f49789c734de22501) ### Monthly AWS bills you at the end of each month for the providers connected and the resources scanned in Prowler Cloud during that month. ### Annual AWS charges the full 12-month subscription once, at checkout. The providers covered by your commitment cost nothing more during the year. Your monthly AWS bill only includes usage beyond the commitment: extra providers at the pay-as-you-go rate, and resources beyond the included amount at the annual plan's per-resource rate. If auto-renewal is on, AWS renews the contract for another 12 months at the end date and charges the new term the same way. Turn it off from **Manage subscriptions** before the renewal date if you do not want that. ## Cancel the Subscription There is no cancel button in Prowler Cloud for AWS Marketplace subscriptions. How you cancel depends on the plan, following the [AWS Marketplace cancellation rules](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html). ### Monthly Cancel from the AWS Marketplace console at any time: 1. Open [Manage subscriptions](https://console.aws.amazon.com/marketplace/subscriptions) and open **Prowler Cloud**. 2. Under **Active agreements**, select the agreement and click **View details**. 3. Open the **Actions** menu and choose **Cancel subscription**. 4. Type `confirm` and choose **Yes, cancel subscription**. ![Prowler Cloud agreement page in the AWS Marketplace console with the Actions menu open on Cancel subscription](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/aws-manage-subscriptions.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=2987bb741b52364a599c16b2cd874078) Cancelling stops future charges. Usage accrued before the cancellation still appears on your next AWS bill. ### Annual Open the agreement from [Manage subscriptions](https://console.aws.amazon.com/marketplace/subscriptions) first. If the **Actions** menu shows **Cancel subscription**, follow the monthly steps above. If it does not, AWS does not allow self-service cancellation for that contract: * **Within 48 hours of purchase**, contact AWS Customer Service. AWS can cancel the contract and refund the full amount, but only if you ask for the refund. * **After 48 hours**, contact [support@prowler.com](mailto:support@prowler.com). Prowler starts the cancellation request through AWS Marketplace and you approve it in the AWS Marketplace console. A refund is not automatic. Ask for it when you request the cancellation. See [Refunds and cancellations in AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-refunds.html) for the AWS side of the process. ### What happens after cancellation Once AWS ends the subscription, Prowler Cloud pauses scans for the organization. Providers, findings and scan history stay readable. A **Subscription required** card in the sidebar, labeled **Subscription cancelled**, explains it: "Scans are paused and your assessment data remains available. Subscribe again to continue scanning." The billing page shows the plan selection page. ![Prowler Cloud after an AWS Marketplace cancellation, showing the Subscription cancelled card in the sidebar and the plan selection page](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/billing-cancelled.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=28c2154a52592b6717f7dbf603ee9629) To subscribe again from the same AWS account into the same Prowler Cloud organization, subscribe from the listing and activate as before. > [!WARNING] > > Deleting your Prowler Cloud organization does not cancel the AWS subscription. AWS keeps charging the agreement until you cancel it as described above. ## Troubleshooting ### Activation errors Each error appears on the Prowler Cloud billing page with the title below. Your AWS purchase is never lost by any of them. **Continue to billing** closes the message without activating. > [accordion] Your AWS Marketplace link has expired > > AWS no longer accepts the setup link, usually because it timed out. AWS documents roughly one hour of validity, and never more than four. > > Open **Manage subscriptions** in the AWS Marketplace console, open **Prowler Cloud**, and click **Set up your account** to get a fresh link. > > ![Error notice: Your AWS Marketplace link has expired](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-token-expired.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=3085a438fb9ec31087d100bd8ec2c9fc) > [accordion] This AWS Marketplace product is not supported yet > > The purchase went through on AWS, but this listing is not enabled for activation in Prowler Cloud. You see this when you subscribed to an earlier Prowler Cloud listing instead of one of the [two current plans](#plans). > > Contact [support@prowler.com](mailto:support@prowler.com) with the AWS account you subscribed with. Click **Try again** once support confirms. > > ![Error notice: This AWS Marketplace product is not supported yet](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-product-not-supported.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=77d8feb2a45635a64211b95772eed71d) > [accordion] This AWS subscription is already linked > > The purchase cannot be linked to the organization you are signed in to. The message shows the reason reported for this purchase: > > * **"This AWS Marketplace subscription is no longer active."** The subscription was cancelled on AWS. Subscribe again from the listing. If you see this seconds after a new purchase, AWS may still be registering it: wait a minute, go back to **Manage subscriptions**, and click **Set up your account** again. > * **"This AWS Marketplace purchase is already linked to another Prowler account."** AWS identifies a purchase by AWS account and product, so one AWS account backs one Prowler Cloud organization per plan. Sign in to the organization that already holds it, or subscribe from a different AWS account. > * **"This account is already linked to another active AWS Marketplace purchase."** This organization already has an active AWS Marketplace subscription. Cancel that subscription in the AWS Marketplace console before activating a new one. > > If none of these applies, contact [support@prowler.com](mailto:support@prowler.com). > > ![Error notice: This AWS subscription is already linked, with the reason shown below the message](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-agreement-in-use.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=9dd68074c61626929a1ae7448eb34ba4) > [accordion] Your purchase is still being linked > > Another request is linking the same purchase, usually a second click or a second tab. Wait a moment and click **Try again**. > > ![Error notice: Your purchase is still being linked](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-link-in-progress.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=86ae4b883f0fa501dc558c08517c80c4) > [accordion] You already have an active subscription > > This organization is billed by credit card. Cancel that subscription first, so you are never charged twice. Then open **Manage subscriptions** in the AWS Marketplace console and click **Set up your account** again. > > ![Error notice: You already have an active subscription](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-billing-provider-conflict.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=35a10004e03c4d7c269e2c4b8c337f46) > [accordion] This AWS purchase is billed under another organization > > AWS Marketplace billing for this AWS account and plan is already set up in a different Prowler Cloud organization. This also happens after you delete the organization that held the subscription and subscribe again from a new one. > > Sign in to the organization that holds the billing and restart the setup from **Manage subscriptions** in the AWS Marketplace console. If that organization no longer exists, contact [support@prowler.com](mailto:support@prowler.com) so they can release the billing link. > [accordion] We could not find your AWS purchase > > Prowler Cloud received no purchase to activate. Open **Manage subscriptions** in the AWS Marketplace console and click **Set up your account** to start again. > > ![Error notice: We could not find your AWS purchase](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-no-agreement.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=138c762253df8983c1df1fa316a60ff6) > [accordion] We could not reach AWS Marketplace > > A temporary problem talking to AWS. Click **Try again**. If it keeps failing, contact [support@prowler.com](mailto:support@prowler.com) and include the detail text shown under the message. > > ![Error notice: We could not reach AWS Marketplace](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-resolve-failed.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=32f9d8001964341c630f8a13a11824d1) > [accordion] We could not activate your subscription > > The purchase was linked but the activation did not complete. Click **Try again**. If it keeps failing, contact [support@prowler.com](mailto:support@prowler.com) and include the detail text shown under the message. > > ![Error notice: We could not activate your subscription](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-subscribe-failed.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=e2f4c05483da61d8a1ae7ce1890c234a) > [accordion] Please sign in again > > Your Prowler Cloud session expired before the activation finished. Click **Sign in again** and pick up where you left off. The setup link stays valid during its expiry window. > > ![Error notice: Please sign in again](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-unauthorized.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=8cca26db3f9acf0ce8cd96891897bb7f) > [accordion] We could not read your AWS purchase > > The setup link arrived damaged. Open **Manage subscriptions** in the AWS Marketplace console and click **Set up your account** to get a fresh one. > > ![Error notice: We could not read your AWS purchase](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/error-invalid-input.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=839fca1f891255cd1c596fb0a47fc1e7) ### Errors before the sign-in page If the redirect from AWS itself fails, Prowler Cloud shows a plain page instead of the app. Each page links back to Prowler Cloud billing and to your AWS Marketplace subscriptions. > [accordion] We couldn't verify this request > > The setup page only accepts the redirect from AWS Marketplace. You reach it by opening the setup URL directly or from a bookmark. Start again from **Set up your account** in the AWS Marketplace console. > > ![Error page: We couldn't verify this request](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/fulfillment-error-verify.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=943b854138bc93e194f264854c078b80) > [accordion] We couldn't read your AWS purchase > > The redirect arrived without a valid setup token. Start again from **Set up your account** in the AWS Marketplace console. > > ![Error page: We couldn't read your AWS purchase](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/fulfillment-error-read.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=61e171af4a80758526788e4c6188d5ec) > [accordion] Something went wrong > > Prowler Cloud could not process the redirect. Your purchase is safe. Wait a moment, then start again from **Set up your account** in the AWS Marketplace console. Contact [support@prowler.com](mailto:support@prowler.com) if it happens again. > > ![Error page: Something went wrong](https://mintcdn.com/prowler/kGWigqD829udcJf4/images/aws-marketplace/fulfillment-error-generic.png?fit=max\&auto=format\&n=kGWigqD829udcJf4\&q=85\&s=28aa5094f543b3c86358ee34d433bbfe) ### SEPA payment method issues If AWS Marketplace notifies that payment failed due to an issue with the payment method, this typically occurs when a SEPA bank account is set as the default payment method. AWS Marketplace does not support SEPA bank accounts for product subscriptions, even when the account includes valid alternative payment methods. This is because AWS Marketplace invoices are issued by AWS Inc., a US entity. SEPA accounts do not recognize these invoices as valid, causing subscription failures. To successfully subscribe to AWS Marketplace products with a SEPA account configuration: 1. Switch default payment method to credit card 2. Complete subscription 3. Switch the default payment method back to the bank account > [!WARNING] > > **Renewal Considerations** > > This issue will recur during subscription renewals. AWS service teams recommend maintaining credit card as the default payment method to prevent future disruptions. Update payment methods at [https://console.aws.amazon.com/billing/home#/paymentmethods](https://console.aws.amazon.com/billing/home#/paymentmethods). > [!NOTE] > > **AWS Marketplace Statement** > > The AWS Marketplace team acknowledges this limitation: "We apologize for these additional steps, and please know we are fully aware of this situation, and our internal teams are working on simplifying this process." ### Credit and debit card storage restrictions (AISPL customers in India) AWS Marketplace no longer supports payments using credit or debit cards stored on file for Amazon Internet Services Private Limited (AISPL) customers. This restriction stems from Reserve Bank of India (RBI) regulations regarding payment aggregators, which prohibit the storage of card data. As explained in [this AWS blog post](https://aws.amazon.com/blogs/awsmarketplace/restriction-on-credit-and-debit-card-purchases-for-aispl-customers-using-aws-marketplace/): > AWS Marketplace can no longer support payments using credit or debit cards stored on file. [The Reserve Bank of India (RBI) has issued a notice regarding regulation of payment aggregators](https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=11822\&Mode=0), which restricts the storage of card data. If you are currently using credit or debit card as your default payment instrument, your ability to use AWS Marketplace products will be restricted. However, you can switch your default payment instrument to Pay By Invoice to avoid disruption or restore your original experience. To maintain uninterrupted access to AWS Marketplace products, change the default payment instrument from stored card data to Pay By Invoice billing. ## Support If you get stuck at any step, contact [support@prowler.com](mailto:support@prowler.com) and include the AWS account you subscribed with and the exact error title you see. # Overview Source: https://docs.prowler.com/getting-started/products/prowler-cloud-lighthouse Prowler Cloud runs an enhanced version of Lighthouse AI in Open Source repository, the Agentic Cloud Defender that helps teams understand, prioritize, and remediate security findings across cloud environments. > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). ![Lighthouse AI on Prowler Cloud](https://mintcdn.com/prowler/44mRBv6pOIPt3HtB/images/prowler-app/lighthouse/prowler-cloud/chat-animation.gif?s=c7e0ca09373c98c886139ea79a0830fe) ## What's New The Agentic Cloud Defender does more than answer questions, it helps teams **find and remediate what actually matters**, cutting through the noise to focus on the risk that counts. Prowler Cloud sharpens Lighthouse AI with the following improvements over the open-source version: > [card] Persistent Chat Sessions > > Conversations are saved and can be revisited or resumed at any time. > [card] GPT-5.5 by Default > > An upgraded default model delivers stronger reasoning and tool calling. > [card] Normal and Agentic Views > > Switch between the standard interface and a chat-first agentic view. > [card] Side Panel on Every Page > > Open Lighthouse AI as a side panel from any page to get help in context. > [card] Provider Connection Checks > > Credentials are validated automatically when a provider is configured. ## Chat View [Added in:  5.33.0](https://github.com/prowler-cloud/prowler/releases/tag/5.33.0) Lighthouse AI is no longer a separate section in the left navigation. Prowler Cloud now offers two application views: a normal view for browsing dashboards, findings, and configuration, and an agentic chat view, powered by Lighthouse AI, for conversational, multi-step security analysis. Conversations are saved automatically, so earlier sessions can be reopened and resumed at any time. Promoting the chat to a top-level view gives Lighthouse AI the room it needs for a fully agentic workflow and makes the Agentic Cloud Defender a primary way to work in Prowler Cloud. ![Lighthouse AI chat view in Prowler Cloud](https://mintcdn.com/prowler/44mRBv6pOIPt3HtB/images/prowler-app/lighthouse/prowler-cloud/main-chat-page.png?fit=max\&auto=format\&n=44mRBv6pOIPt3HtB\&q=85\&s=edd9415bbb18f91ca58932347735db28) ### Side Panel [Added in:  5.35.0](https://github.com/prowler-cloud/prowler/releases/tag/5.35.0) You do not have to switch to the full chat view to reach Lighthouse AI. A side panel is available on every page of Prowler Cloud. While collapsed it stays out of the way; open it from any dashboard, findings list, or configuration screen to ask questions without leaving what you are working on. Open it using the Lighthouse AI button, circled in red in the image below. ![Collapsed Lighthouse AI side panel on a Prowler Cloud page, with the button to open it circled in red](https://mintcdn.com/prowler/1CG5-eXrFf99dNG8/images/prowler-app/lighthouse/prowler-cloud/side-panel-closed.png?fit=max\&auto=format\&n=1CG5-eXrFf99dNG8\&q=85\&s=7c4811ee30f5e0a590e317f561af9592) Once open, the panel slides in alongside your current page and shares the same agent, tools, and persistent chat sessions as the full Chat View, so a conversation started in the panel can be reopened and continued later from either place. ![Lighthouse AI side panel open alongside a Prowler Cloud page](https://mintcdn.com/prowler/1CG5-eXrFf99dNG8/images/prowler-app/lighthouse/prowler-cloud/side-panel-open.png?fit=max\&auto=format\&n=1CG5-eXrFf99dNG8\&q=85\&s=1977d0353b183140b6e2d47d553bd2a7) * **Available everywhere:** Summon the assistant from any page while you keep working in the normal view. * **Context-aware help:** Ask about the findings, resources, or compliance data you are currently looking at. * **Continuous sessions:** Conversations opened in the side panel are saved alongside the rest of your chat history. ### Context-Aware Chat [Added in:  5.37.0](https://github.com/prowler-cloud/prowler/releases/tag/5.37.0) The panel knows where you are in the app. Messages carry the page you are on and, when a finding or resource is open in the side panel, its metadata too, so questions like "explain this" resolve against what is on screen. The active context appears as a chip in the composer, circled in red in the image below, and each page offers contextual suggestions to start from. ![Lighthouse AI answering a question about the open finding from the side panel, with the page context chip highlighted in red in the composer](https://mintcdn.com/prowler/y2Qml-1Q66KeL6CI/images/prowler-app/lighthouse/prowler-cloud/side-panel-context-aware.png?fit=max\&auto=format\&n=y2Qml-1Q66KeL6CI\&q=85\&s=ccf008d9a523c9585bc303a4f8465794) ### Tool Usage Lighthouse AI on Prowler Cloud renders the agent's work as it happens, so responses are easier to follow and to trust. Tool calls and reasoning steps appear in the order they occur within the conversation. * **Ordered steps:** Tool calls and reasoning are shown in sequence, reflecting how the agent reached its answer. * **Tool visibility:** The data tools invoked to retrieve findings and other Prowler information are displayed as the agent uses them. * **Thought process:** The agent's reasoning is presented alongside its actions, and can be expanded to review the full chain of steps. ![Ordered tool usage and reasoning in the Lighthouse AI chat](https://mintcdn.com/prowler/44mRBv6pOIPt3HtB/images/prowler-app/lighthouse/prowler-cloud/tool-usage.png?fit=max\&auto=format\&n=44mRBv6pOIPt3HtB\&q=85\&s=71199fb8ad3b0bd646f53b3a54e6a610) ## Configuration Configure Lighthouse AI on Prowler Cloud from **Configuration** → **Lighthouse AI**: 1. Click the desired provider (OpenAI, Amazon Bedrock, or OpenAI Compatible). 2. Enter the required credentials. 3. Click **Save**. The connection is validated automatically before the provider becomes available. ![Lighthouse AI configuration page in Prowler Cloud](https://mintcdn.com/prowler/44mRBv6pOIPt3HtB/images/prowler-app/lighthouse/prowler-cloud/config-page.png?fit=max\&auto=format\&n=44mRBv6pOIPt3HtB\&q=85\&s=60a01816703e99544acc514246f43aa7) ### Business Context At the top of the configuration page, the optional **Business Context** field lets teams add environment priorities, compliance requirements, and ownership details, so responses align with organizational needs. Lighthouse AI on Prowler Cloud supports OpenAI, Amazon Bedrock, and OpenAI-compatible providers, with GPT-5.5 as the default. For per-provider setup and how to switch the default provider or model, see [Using Multiple LLM Providers](/user-guide/tutorials/prowler-cloud-lighthouse-multi-llm). ## Capabilities Lighthouse AI works through the [Prowler MCP Server](/getting-started/products/prowler-mcp), which gives the agent a growing catalog of tools to explore and act on your security data. These actions run inside Prowler and never modify your cloud resources. Everything the agent can do maps to one of the following capability areas. ### Findings and Finding Groups * Search and filter security findings across every connected provider by severity, status, region, service, check, date range, and muted state. * Retrieve full finding details, including remediation guidance, check metadata, and affected resources. * Summarize findings with aggregate statistics and trends. * Browse finding groups aggregated by check and drill down into the specific resources each group affects. ### Resources * List and filter cloud resources by provider, region, service, resource type, and tags. * Inspect a resource's configuration, metadata, and related findings. * Review the timeline of cloud API actions performed on a resource (AWS CloudTrail), including who did what and when. * Get an aggregate overview of the resources Prowler has discovered. ### Compliance * Review high-level compliance status across all frameworks, with pass/fail statistics per framework. * Get a requirement-level breakdown for a specific framework, including failed requirements and their associated findings. ### Attack Paths * List Attack Paths scans and discover the queries available for each completed scan. * Run graph-based queries to reveal privilege-escalation chains and exploitable misconfigurations. * Retrieve the Cartography graph schema to build accurate custom queries. ### Scans and Providers * List, inspect, and rename security scans across providers. * Trigger manual scans and schedule automated daily scans for continuous monitoring. * Search connected providers and check their connection status, connect new providers, or remove existing ones. ### Muting * Manage the mutelist for pattern-based bulk muting. * Create, update, list, and delete finding-specific mute rules, each with a documented reason and audit trail. ### Security Check Catalog and Documentation * Browse and search the Prowler Hub catalog of security checks and compliance frameworks, including check code and automated fixers. * Search and retrieve official Prowler documentation to answer how-to and product questions. For the complete list of underlying tools, see the [Prowler MCP Tools Reference](/getting-started/basic-usage/prowler-mcp-tools). ## FAQ **Which LLM providers are supported?** OpenAI (GPT models, including the default GPT-5.5), Amazon Bedrock (Claude, Llama, Titan, and others), and any OpenAI-compatible service such as OpenRouter. **Can Lighthouse AI change my cloud environment?** No. Lighthouse AI cannot modify the resources in your connected cloud providers (AWS, Azure, GCP, and others). It has read-only access to that environment and no tools to change it, even when the connected cloud credentials would allow it. **Can Lighthouse AI change my Prowler Cloud environment?** Yes. Lighthouse AI can take action within Prowler Cloud itself, such as connecting or removing providers, triggering and scheduling scans, and managing mute rules and the mutelist. See [Capabilities](#capabilities) for the full list of what it can do. These actions only affect your Prowler Cloud workspace, never the resources in your cloud providers. ## Looking for the Open Source Version? Lighthouse AI is also available in the open-source Prowler Local Server. For its capabilities, FAQs, and limitations, see the open-source documentation. > [card] [Lighthouse AI (Open Source)](/getting-started/products/prowler-lighthouse-ai) > > Capabilities, FAQs, and limitations for Lighthouse AI in the open-source Prowler Local Server ## Getting Help For issues or suggestions with Lighthouse AI on Prowler Cloud, request support at [support.prowler.com](https://support.prowler.com) or [reach out through our Slack channel](https://goto.prowler.com/slack). # Pricing Source: https://docs.prowler.com/getting-started/products/prowler-cloud-pricing # Prowler for MSPs and MSSPs Source: https://docs.prowler.com/getting-started/products/prowler-for-msps Prowler for MSPs and MSSPs is a dedicated console for Managed Service Providers (MSPs), Managed Security Service Providers (MSSPs), resellers and consultants who run cloud security for other organizations. It lets a provider onboard customers, group them, manage a team, and operate each customer's Prowler Cloud tenant on their behalf. The console is available at [partners.prowler.com](https://partners.prowler.com). > [card] [Sign Up for Prowler for MSPs and MSSPs](https://partners.prowler.com/sign-up) ## What You Get * **Customer onboarding:** provision a Prowler Cloud tenant for each customer, with a billing plan selected up front. * **Delegated access:** open any customer's Prowler Cloud tenant from the console. Every action is attributed to you acting on behalf of that customer. * **Team and roles:** invite team members by email and assign a role that governs what they can do. * **Consolidated billing:** each customer carries its own plan, with month-to-date revenue reported across every customer. * **Branding:** upload your logo and preview its intended placement in Settings. ## Core Concepts Three objects make up the model. Getting these straight makes the rest of the documentation easy to follow. | Object | What it is | | - | - | | **Partner organization** | The provider's own company. The top-level container for everything below, created at sign-up. | | **Customer** | One of the provider's customers. Each customer maps to a Prowler Cloud tenant and carries its own billing plan. | | **Team member** | A user in the partner organization, holding a role that governs what they can do. | ## How It Relates to Prowler Cloud | | Prowler Cloud | Prowler for MSPs and MSSPs | | - | - | - | | **Audience** | End customers | MSPs, MSSPs, resellers, consultants | | **Console** | [cloud.prowler.com](https://cloud.prowler.com) | [partners.prowler.com](https://partners.prowler.com) | | **Scope** | One organization's own cloud accounts | Many customer organizations | | **Billing** | Each organization pays for itself | The provider manages a plan per customer | | **Branding** | Prowler-branded | Logo upload and placement preview in Settings | Your customers keep signing in to Prowler Cloud with their own users. Provider-side access is **additive** — it does not replace or restrict customer-side users. ## The Console at a Glance Signing in lands you on the **Dashboard**. The sidebar carries: | Entry | What it does | Visible to | | - | - | - | | **Dashboard** | Partner Insights, a Billing Overview card and an Active Customers table | Everyone | | **Customers** | Review customer posture and billing and open customer tenants; Superadmins can also add customers | Everyone | | **Team** | Invite, re-invite, disable and remove team members | Roles with **Manage members** | | **Settings** | Profile, Partner Code, branding and security | Everyone; editing requires **Manage settings** | ![Prowler for MSPs and MSSPs dashboard](https://mintcdn.com/prowler/8SpCQ5j6hzsCrM33/images/prowler-for-msps/dashboard.png?fit=max\&auto=format\&n=8SpCQ5j6hzsCrM33\&q=85\&s=265d45d769003b6d329bd519cd079052) **Partner Insights** is the top row: **Total Customers**, broken down into active and non-paid; **Cloud Accounts**, broken down by cloud provider; and **Monitored Resources**, with a note on organizations whose critical risk has grown. Each card carries a 30-day trend. Below it, **Billing Overview** reports monthly expenses against the previous month and splits revenue for the period into annual, monthly and overage. **Active Customers** lists your customers with their provider count, resource count and last completed scan and, for Superadmins, carries its own **Add Customer** button. ## Getting Access Sign-up is self-service, approval is not. Register at [partners.prowler.com/sign-up](https://partners.prowler.com/sign-up), then verify your email address — the organization sits in **Pending email verification** until you do, and the Prowler team does not review it before that. Verifying moves the organization to **Pending approval**. Once approved, you can invite your team and start onboarding customers. ## Next Steps > [card] [Sign Up and Sign In](/user-guide/tutorials/prowler-for-msps-sign-up) > > Register, verify your email, and get approved. > [card] [Your Partner Organization](/user-guide/tutorials/prowler-for-msps-organization) > > Lifecycle, settings, Partner Code and closing your organization. > [card] [Onboarding Customers](/user-guide/tutorials/prowler-for-msps-customers) > > Add customers and open their Prowler Cloud tenants. > [card] [Managing Your Team](/user-guide/tutorials/prowler-for-msps-team) > > Invite team members and assign roles. # Overview Source: https://docs.prowler.com/getting-started/products/prowler-hub **Prowler Hub** is our growing public library of versioned checks, cloud service artifacts, and compliance frameworks with its mappings. It’s searchable, explainable, and built to serve the community. **Why this matters**: Every engineer has asked, “What does this check actually do?” Prowler Hub answers that question in one place, lets you pin to a specific version, and pulls definitions into your own tools or dashboards. ![](https://mintcdn.com/prowler/h-JuXC13FJjn4hV6/images/products/prowler-hub.png?fit=max\&auto=format\&n=h-JuXC13FJjn4hV6\&q=85\&s=97875dbc548ed6b206f04ca3826930bc) > [card] [Go to Prowler Hub](https://hub.prowler.com) Prowler Hub also provides a fully documented public API that you can integrate into your internal tools, dashboards, or automation workflows. 📚 Explore the API docs at: [https://hub.prowler.com/api/docs](https://hub.prowler.com/api/docs) Whether you’re customizing policies, managing compliance, or enhancing visibility, Prowler Hub is built to support your security operations. # Overview Source: https://docs.prowler.com/getting-started/products/prowler-lighthouse-ai [Added in:  5.8.0](https://github.com/prowler-cloud/prowler/releases/tag/5.8.0) Prowler Lighthouse AI is a Cloud Security Analyst chatbot that helps you understand, prioritize, and remediate security findings in your cloud environments. It's designed to provide security expertise for teams without dedicated resources, acting as your 24/7 virtual cloud security analyst. ![Prowler Lighthouse](https://mintcdn.com/prowler/Y2u1AlcEta6b7teE/images/prowler-app/lighthouse/oss/intro.png?fit=max\&auto=format\&n=Y2u1AlcEta6b7teE\&q=85\&s=88873eed8e60910fb2ae4bd925350872) > [card] [Lighthouse AI on Prowler Cloud](/getting-started/products/prowler-cloud-lighthouse) > > Discover the enhanced Cloud experience: persistent chat sessions, GPT-5.5 by default, a dedicated agentic view, and transparent reasoning > [card] [Set Up Lighthouse AI](/user-guide/tutorials/prowler-app-lighthouse#set-up) > > Learn how to configure Lighthouse AI with your preferred LLM provider ## Capabilities Prowler Lighthouse AI is designed to be your AI security team member, with capabilities including: ### Natural Language Querying Ask questions in plain English about your security findings. Examples: * "What are my highest risk findings?" * "Show me all S3 buckets with public access." * "What security issues were found in my production accounts?" ![Natural language querying](https://mintcdn.com/prowler/Y2u1AlcEta6b7teE/images/prowler-app/lighthouse/oss/feature1.png?fit=max\&auto=format\&n=Y2u1AlcEta6b7teE\&q=85\&s=ce7fb62aed554aba2da52b3bbe72c7dd) ### Detailed Remediation Guidance Get tailored step-by-step instructions for fixing security issues: * Clear explanations of the problem and its impact * Commands or console steps to implement fixes * Alternative approaches with different solutions ![Detailed Remediation](https://mintcdn.com/prowler/Y2u1AlcEta6b7teE/images/prowler-app/lighthouse/oss/feature2.png?fit=max\&auto=format\&n=Y2u1AlcEta6b7teE\&q=85\&s=eba91c90edefee8f69e6c69963e5fc84) ### Enhanced Context and Analysis Lighthouse AI can provide additional context to help you understand the findings: * Explain security concepts related to findings in simple terms * Provide risk assessments based on your environment and context * Connect related findings to show broader security patterns ![Business Context](https://mintcdn.com/prowler/Y2u1AlcEta6b7teE/images/prowler-app/lighthouse/oss/config.png?fit=max\&auto=format\&n=Y2u1AlcEta6b7teE\&q=85\&s=c98901b4e5f58e69e408d7ceb8dffb09) ![Contextual Responses](https://mintcdn.com/prowler/Y2u1AlcEta6b7teE/images/prowler-app/lighthouse/oss/feature3.png?fit=max\&auto=format\&n=Y2u1AlcEta6b7teE\&q=85\&s=63003f1436cc671b0476d6040748daa1) ## Important Notes Prowler Lighthouse AI is powerful, but there are limitations: * **Continuous improvement**: Please report any issues, as the feature may make mistakes or encounter errors, despite extensive testing. * **Access limitations**: Lighthouse AI can only access data the logged-in user can view. If you can't see certain information, Lighthouse AI can't see it either. * **NextJS session dependence**: If your Prowler application session expires or logs out, Lighthouse AI will error out. Refresh and log back in to continue. * **Response quality**: The response quality depends on the selected LLM provider and model. Choose models with strong tool-calling capabilities for best results. We recommend `gpt-5` model from OpenAI. ## Architecture ![Prowler Lighthouse Architecture](https://mintcdn.com/prowler/dxKr6jfROeYV7A0M/images/lighthouse-architecture.png?fit=max\&auto=format\&n=dxKr6jfROeYV7A0M\&q=85\&s=0660e8227b6a43de0c74b393185709e6) ## Extending Lighthouse AI Lighthouse AI retrieves data through Prowler MCP. To add new capabilities, extend the Prowler MCP Server with additional tools and Lighthouse AI discovers them automatically. For development details, see: * [Lighthouse AI Architecture](/developer-guide/lighthouse-architecture) - Internal architecture and extension points * [Extending the MCP Server](/developer-guide/mcp-server) - Adding new tools to Prowler MCP ### Getting Help If you encounter issues with Prowler Lighthouse AI or have suggestions for improvements, please [reach out through our Slack channel](https://goto.prowler.com/slack). ### What Data Is Shared to LLM Providers? The following API endpoints are accessible to Prowler Lighthouse AI. Data from the following API endpoints could be shared with LLM provider depending on the scope of user's query: ## FAQs **1. Which LLM providers are supported?** Lighthouse AI supports three providers: * **OpenAI** - GPT models (GPT-5, GPT-4o, etc.) * **Amazon Bedrock** - Claude, Llama, Titan, and other models via AWS * **OpenAI Compatible** - Custom endpoints like OpenRouter, Ollama, or any OpenAI-compatible service For detailed configuration instructions, see [Using Multiple LLM Providers with Lighthouse](/user-guide/tutorials/prowler-app-lighthouse-multi-llm). **2. Why don't some models appear in Lighthouse AI?** LLM providers offer different types of models. Not every model can be integrated with Lighthouse AI (for example, text-to-speech, vision, embedding, computer use, etc.). Lighthouse AI requires models that support: * Text input * Text output * Tool calling Lighthouse AI [automatically filters](https://github.com/prowler-cloud/prowler/blob/master/api/src/backend/tasks/jobs/lighthouse_providers.py#L341-L353) out models that do not support these capabilities, so some provider models may not appear in the Lighthouse AI model list. **3. Is my security data shared with LLM providers?** Minimal data is shared to generate useful responses. Agent can access security findings and remediation details when needed. Provider secrets are protected by design and cannot be read. The LLM provider credentials configured with Lighthouse AI are only accessible to the Next.js server and are never sent to the LLM providers. Resource metadata (names, tags, account/project IDs, etc.) may be shared with the configured LLM provider based on query requirements. **4. Can the Lighthouse AI change my cloud environment?** No. The agent doesn't have the tools to make the changes, even if the configured cloud provider API keys contain permissions to modify resources. # Overview Source: https://docs.prowler.com/getting-started/products/prowler-mcp **Prowler MCP Server** brings the entire Prowler ecosystem to AI assistants through the Model Context Protocol (MCP). It enables seamless integration with AI tools like Claude Desktop, Cursor, and other MCP clients, allowing interaction with Prowler's security capabilities through natural language. > [!WARNING] > > **Preview Feature**: This MCP server is currently under active development. Features and functionality may change. We welcome your feedback—please report any issues on [GitHub](https://github.com/prowler-cloud/prowler/issues) or join our [Slack community](https://goto.prowler.com/slack) to discuss and share your thoughts. ## Quickest Way to Connect: Cloud MCP Server The fastest way to get started is the **Cloud MCP Server** at `https://mcp.prowler.com/mcp` — no installation, always up to date, and maintained by Prowler. Just point your MCP client at the URL and authenticate with a [Prowler API key](/user-guide/tutorials/prowler-app-api-keys) as a Bearer token: ```json theme={null} { "mcpServers": { "prowler": { "url": "https://mcp.prowler.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` > [card] [Connect Your MCP Client to the Cloud MCP Server](/getting-started/basic-usage/prowler-mcp#cloud-mcp-server-configuration-recommended) > > Step-by-step setup for Claude Code, Codex, Cursor, VS Code, and other agents. > [!NOTE] > > Prefer to run it yourself? The **Local MCP Server** runs on your own machine or infrastructure. The Cloud MCP Server additionally provides the `prowler_cloud_*` tools for Prowler Cloud-specific features: [Alerts](/user-guide/tutorials/prowler-alerts), [Findings Triage](/user-guide/tutorials/prowler-app-findings-triage), [Scan Scheduling](/user-guide/tutorials/prowler-scan-scheduling), and Scan Configurations. See [Cloud vs Local MCP Server](#cloud-vs-local-mcp-server). ## What is the Model Context Protocol? The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard developed by Anthropic that enables AI assistants to securely connect to external data sources and tools. It functions as a universal adapter enabling AI assistants to interact with various services through a standardized interface. ## Key Capabilities The Prowler MCP Server provides four integration points: ### 1. Prowler Cloud, Private Cloud & Local Server Full access to your Prowler deployment — Prowler Cloud, Prowler Private Cloud, or Prowler Local Server — for: * **Findings Analysis**: Query, filter, and analyze security findings across all your cloud environments * **Provider Management**: Create, configure, and manage your configured Prowler providers (AWS, Azure, GCP, etc.) * **Scan Orchestration**: Trigger on-demand scans, track their progress, and schedule a daily scan * **Resource Inventory**: Search and view detailed information about your audited resources * **Muting Management**: Create and manage muting lists/rules to suppress non-relevant findings * **Attack Paths Analysis**: Analyze privilege escalation chains and security misconfigurations through graph-based analysis of cloud resource relationships * **Integrations Management**: Set up and troubleshoot where Prowler sends its results (Amazon S3, AWS Security Hub, Jira), and turn findings into Jira work items * **User & Role Management**: List the users in your tenant, identify the authenticated user, browse RBAC roles, and set the role a user holds ### 2. Prowler Cloud Management Prowler Cloud-only tools for configuration and workflows that a Prowler Local Server does not provide. These are exposed only by the [Cloud MCP Server](#cloud-vs-local-mcp-server): * **Scan Configurations**: Create reusable check and compliance selections and attach them to providers. * **Findings Triage**: Record review statuses and notes for individual findings, without suppressing them. * **Scan Scheduling**: Configure daily, interval, weekly, or monthly recurring scans, one provider at a time or in bulk. * **Alerts**: Build and dry-run alert rule conditions, manage email recipients, and review fired alerts. ### 3. Prowler Hub Access to Prowler's comprehensive security knowledge base: * **Security Checks Catalog**: Browse and search **over 2,000 security checks** across multiple cloud providers. * **Check Implementation**: View the Python code that powers each security check. * **Automated Fixers**: Access remediation scripts for common security issues. * **Compliance Frameworks**: Explore mappings to **over 70 compliance standards and frameworks**. * **Provider Services**: View available services and checks for each cloud provider. ### 4. Prowler Documentation Search and retrieve official Prowler documentation: * **Intelligent Search**: Full-text search across all Prowler documentation. * **Contextual Results**: Get relevant documentation pages with highlighted snippets. * **Document Retrieval**: Access complete markdown content of any documentation file. ## MCP Server Architecture The following diagram illustrates the Prowler MCP Server architecture and its integration points. MCP clients connect to either the **Cloud MCP Server** (recommended) or a **Local MCP Server**. Both reach the same Prowler backends and share the `prowler_*`, `prowler_hub_*`, and `prowler_docs_*` tools; the Cloud MCP Server additionally exposes the Cloud-only `prowler_cloud_*` tools: ```mermaid theme={null} flowchart LR subgraph HOSTS["MCP Clients"] chat["Chat Interfaces
(Claude Desktop, LobeChat)"] ide["IDEs and Code Editors
(Claude Code, Cursor)"] apps["Other AI Applications
(5ire, custom agents)"] end subgraph SERVERS["Prowler MCP Server"] direction TB cloud["Cloud MCP Server (Recommended)
mcp.prowler.com/mcp · HTTP
Managed by Prowler · always up to date
Adds the Cloud-only prowler_cloud_* tools"] local["Local MCP Server
Self-run · STDIO or HTTP
Python 3.12+ or Docker
You manage updates"] end subgraph TOOLS["Prowler MCP Tools"] prowler_tools["prowler_* tools
(API key or JWT auth)
Findings · Finding Groups · Providers
Scans · Resources · Muting · Compliance
Attack Paths · Integrations · Users · Roles"] cloud_tools["prowler_cloud_* tools
(API key or JWT auth · Cloud only)
Alerts · Findings Triage
Scan Scheduling · Scan Configurations"] hub_tools["prowler_hub_* tools
(no auth)
Checks Catalog · Check Code
Fixers · Compliance Frameworks"] docs_tools["prowler_docs_* tools
(no auth)
Search · Document Retrieval"] end api["Prowler API (REST)
Cloud · Private Cloud · Local Server"] hub["hub.prowler.com
(REST)"] docs["docs.prowler.com
(Mintlify)"] chat -->|HTTP| cloud ide -->|HTTP| cloud apps -->|HTTP| cloud chat -->|STDIO or HTTP| local ide -->|STDIO or HTTP| local apps -->|STDIO or HTTP| local cloud --> prowler_tools cloud --> cloud_tools cloud --> hub_tools cloud --> docs_tools local --> prowler_tools local --> hub_tools local --> docs_tools prowler_tools -->|REST| api cloud_tools -->|REST| api hub_tools -->|REST| hub docs_tools -->|REST| docs ``` The architecture shows how AI assistants connect through the MCP protocol to access Prowler's four namespaced components: * Prowler Cloud, Prowler Private Cloud, or Prowler Local Server for security operations * Prowler Cloud management for Cloud-only configuration and workflows * Prowler Hub for security knowledge * Prowler Documentation for guidance and reference. ## Use Cases The Prowler MCP Server enables powerful workflows through AI assistants: **Security Operations** * "Show me all critical findings from my AWS production accounts" * "Register my new AWS account in Prowler and run a scheduled scan every day" * "List all muted findings and flag the ones whose mute reason is too weak for their severity" * "Run an attack paths query to find EC2 instances exposed to the Internet with access to sensitive S3 buckets" * "Send my failed CIS findings for this provider to Jira as work items" **Prowler Cloud Management** (Cloud MCP Server only) * "Preview an alert rule for critical AWS findings and create it for my confirmed recipients" * "Show the triage notes for this finding and mark it as under review" * "Apply a weekly Monday 06:00 scan schedule to every AWS provider" * "Create a scan configuration that runs only CIS checks and attach it to my production providers" **Security Research** * "Explain what the S3 bucket public access Prowler check does" * "Find all Prowler checks related to encryption at rest" * "What is the latest version of the CIS that Prowler is covering per provider?" **Documentation & Learning** * "How do I configure Prowler to scan my GCP organization?" * "What authentication methods does Prowler support for Azure?" * "How can I contribute with a new security check to Prowler?" ### Example: Creating a Custom Dashboard with Prowler Extracted Data In the next example you can see how to create a dashboard using Prowler MCP Server and Claude Desktop. **Used Prompt:** ``` Generate me a security dashboard for the Prowler open source project using live data from Prowler MCP tools. REQUIREMENTS: 1. Fetch real-time data from Prowler Findings using MCP tools 2. Create a single self-contained HTML file and display it 3. Dashboard must be production-ready with modern design DATA TO FETCH: Use these MCP tools in this order: 1. Prowler list providers - To get all available configured provider in the account 2. Prowler get latest findings - To get findings information, if there are so many you can use the filter_fields to get less information, or pagination to get in different batches 3. For most critical findings you can get more context and remediation with Prowler Hub to get remediations for example DESIGN REQUIREMENTS: - Dark theme (gradient background: #0a0e27 to #131830) - Card-based layout with glassmorphism effects - Color scheme:  * Primary green  * Secondary purple - Modern, professional look - Animated "LIVE DATA" indicator (pulsing green badge) - Hover effects on all cards (lift, glow, border color change) - Responsive grid layout - Mobile-responsive breakpoints at 768px - Single HTML file with all CSS and JavaScript embedded - No external dependencies SPECIFIC DETAILS TO INCLUDE: - Show actual counts from the data (don't hardcode numbers) - Add timestamp showing when dashboard was generated - Link to GitHub repository: https://github.com/prowler-cloud/prowler OUTPUT: Generate the complete HTML file and display it ``` **Video:** [Prowler MCP Server - Creating a dashboard](https://www.youtube.com/embed/li29KNmYd4g?si=P3m6eB2z0Cqqse_H) ## Cloud vs Local MCP Server There are two ways to run the Prowler MCP Server. For almost everyone, the **Cloud MCP Server** is the right choice — it needs no installation and is maintained by Prowler. The **Local MCP Server** exists for users who need to run it on their own machine or infrastructure. | | ☁️ **Cloud MCP Server** (Recommended) | 💻 **Local MCP Server** | | - | - | - | | **Cloud-only tools** (`prowler_cloud_*`) | ✅ Alerts, Findings Triage, Scan Scheduling, Scan Configurations | ❌ Not available | | **Endpoint** | `https://mcp.prowler.com/mcp` | Runs on your machine or infrastructure | | **Setup** | Just configure your MCP client | Install via Docker, or source | | **Transport** | HTTP | STDIO (subprocess) or self-hosted HTTP | | **Maintenance** | Managed by Prowler, always up to date | You manage updates | | **Requirements** | None (just an MCP client) | Python 3.12+ or Docker | | **Authentication** | API key or JWT token | API key/JWT (HTTP) or env vars (STDIO) | ### ☁️ Cloud MCP Server (Recommended) Prowler's managed MCP server at `https://mcp.prowler.com/mcp`. No installation, always up to date, and it includes the `prowler_cloud_*` tools for Prowler Cloud-specific features: Alerts, Findings Triage, Scan Scheduling, and Scan Configurations. This is the path we recommend for nearly all users — go straight to the [Configuration guide](/getting-started/basic-usage/prowler-mcp#cloud-mcp-server-configuration-recommended). ### 💻 Local MCP Server Run the server yourself when you need full control over the deployment. It connects to Prowler Cloud, Prowler Private Cloud, or Prowler Local Server and can run in two modes: * **STDIO mode** — the server runs as a subprocess of your MCP client. Authentication via environment variables. * **Self-hosted HTTP mode** — deploy your own remote HTTP server. Authentication via API key or JWT token. Both require Python 3.12+ or Docker, plus network access to `https://hub.prowler.com` (Prowler Hub), `https://docs.prowler.com` (Prowler Documentation), and the Prowler API or Prowler Local Server API (Prowler features). See the [Installation guide](/getting-started/installation/prowler-mcp) to get started. > [!NOTE] > > **No Authentication Required**: Prowler Hub and Prowler Documentation features work without authentication on both the Cloud and Local MCP Server. A Prowler API key is only required to access Prowler features (Prowler Cloud, Prowler Private Cloud, or Prowler Local Server). ## Next Steps > [card] [Configuration](/getting-started/basic-usage/prowler-mcp) > > Connect your MCP client to the Cloud MCP Server > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools and capabilities > [card] [Local Installation](/getting-started/installation/prowler-mcp) > > Run the Local MCP Server yourself using Docker, source, or uvx # Prowler Private Cloud Source: https://docs.prowler.com/getting-started/products/prowler-private-cloud-aws-marketplace Choose a plan, install Prowler Private Cloud in your own AWS account from AWS Marketplace, and understand billing and infrastructure cost. > [!NOTE] > > **Now available on AWS Marketplace.** Install Prowler Private Cloud in your own AWS account and pay on your AWS bill, with three plans: Pay as You Go, 10-Account Bundle and 25-Account Bundle. [Choose a plan](#choose-a-plan). Prowler Private Cloud is the full Prowler platform, installed in the customer's own AWS account from AWS Marketplace and billed on the AWS bill. Findings, resource data and Lighthouse AI prompts stay in that account and Region. > [!NOTE] > > For AWS GovCloud (US), an air-gapped environment, an on-premises data center, or a different bundle size or contract term, [contact us](https://prowler.com/contact) for a private offer. ## Choose a Plan Each plan is its own AWS Marketplace listing. All three install the same product and differ only in how many cloud accounts the price covers: * **Paid accounts:** AWS accounts, Azure subscriptions and Microsoft 365 tenants. * **Other accounts:** everything else Prowler scans, such as Google Cloud projects, Kubernetes clusters, GitHub and Okta. | Plan | Price | Included every month | Extra accounts | | - | - | - | - | | [Pay as You Go](https://aws.amazon.com/marketplace/pp/prodview-cpfki233rkskw) | 125 USD per paid account per month, no minimum | 1 other account per paid account | 125 USD each per month | | [10-Account Bundle](https://aws.amazon.com/marketplace/pp/prodview-2pgvyyakt34go) | 1,000 USD per month, or 9,600 USD for 12 months upfront | 10 paid and 15 other accounts | 125 USD each per month | | [25-Account Bundle](https://aws.amazon.com/marketplace/pp/prodview-ugxkxhdxfrhse) | 2,000 USD per month, or 19,200 USD for 12 months upfront | 25 paid and 40 other accounts | 125 USD each per month | ### Example: Pay as You Go A month with 4 AWS accounts and 6 Google Cloud projects scanned: | Charge | Quantity × price | Subtotal | | - | - | - | | Paid accounts (the 4 AWS accounts) | 4 × 125 USD | 500 USD | | Included other accounts (4 Google Cloud projects, 1 per paid account) | 4 × 0 USD | 0 USD | | Extra accounts (the other 2 Google Cloud projects) | 2 × 125 USD | 250 USD | | **Total** | | **750 USD** | ### Infrastructure Cost AWS bills the infrastructure the installation runs on separately, at AWS prices. With the default size in us-east-1, it costs about 360 USD a month before scans. Scans add to that: each scan runs as its own task at about 0.12 USD for every hour it runs, and the database grows while scans run. A scan of one AWS account usually takes: * **Up to 2,000 resources:** about 10 minutes. * **2,000 to 10,000 resources:** about 25 minutes. * **Over 10,000 resources:** about an hour. For example, 10 AWS accounts scanned once a day, at about 20 minutes each: | Item | Value | | - | - | | Scans per month | 10 accounts × 30 days = 300 scans | | Scan time per month | 300 scans × 1/3 hour = 100 hours | | **Scan cost per month** | **100 hours × 0.12 USD = about 12 USD** | Other Regions cost more than us-east-1. Amazon Bedrock is billed per use, only when Lighthouse AI is on. > [!NOTE] > > These figures are estimates based on AWS public list prices. AWS bills the infrastructure directly to your account, and the final amount depends on your Region, usage and any discounts you have with AWS. Prowler does not set or charge these costs. > [accordion] Infrastructure cost breakdown > > About 360 USD a month for the default size in us-east-1, at AWS list prices, before scans: > > | Resource | About, per month | > | - | - | > | Amazon Elastic Container Service (ECS) on AWS Fargate (Prowler services) | 177 USD | > | Amazon Aurora PostgreSQL | 47 USD | > | Amazon ElastiCache | 37 USD | > | Network address translation (NAT) gateway | 37 USD | > | Application Load Balancer and AWS Web Application Firewall (WAF) | 28 USD | > | Amazon CloudWatch | 22 USD | > | Other AWS services | 10 USD | ## How It Works The installation runs in the customer's AWS account, in the chosen Region. Users reach it through an Amazon CloudFront address, or a [custom domain](#updates-and-settings). Everything else runs in private subnets that cannot be reached from the internet. Scans use read-only access to the connected cloud accounts, and Prowler has no access to the installation. ![Prowler Private Cloud on AWS: users reach Amazon CloudFront, which connects to an internal load balancer in a private network; the Prowler services run on Amazon ECS, with Amazon Aurora and Amazon ElastiCache for data and other AWS services in the same account; scans reach the connected accounts with read-only access](https://mintcdn.com/prowler/FBNM4da6gOzIpM3N/images/products/architecture/prowler-private-cloud-aws-architecture-light.svg?fit=max\&auto=format\&n=FBNM4da6gOzIpM3N\&q=85\&s=a43c17ea69c6a6e8ecf0cc7f30e7d9b7) ## Install Prowler Private Cloud **1. Subscribe on AWS Marketplace** Open the plan's listing on AWS Marketplace (links in [Choose a Plan](#choose-a-plan)), click **View purchase options**, and subscribe. Then continue to the configuration and to launch. The launch page has a link that opens the AWS CloudFormation console with the Prowler template already loaded. **2. Choose a Supported Region** Before creating the stack, switch the console to a supported Region at the top right. The template refuses the others. > [accordion] Supported Regions > > | Region code | Region name | Lighthouse AI | > | - | - | - | > | us-east-1 | US East (N. Virginia) | Available | > | us-east-2 | US East (Ohio) | Available | > | us-west-1 | US West (N. California) | Not available | > | us-west-2 | US West (Oregon) | Available | > | ca-central-1 | Canada (Central) | Not available | > | sa-east-1 | South America (São Paulo) | Available | > | eu-west-1 | Europe (Ireland) | Available | > | eu-west-2 | Europe (London) | Available | > | eu-west-3 | Europe (Paris) | Not available | > | eu-central-1 | Europe (Frankfurt) | Available | > | eu-north-1 | Europe (Stockholm) | Available | > | ap-east-1 | Asia Pacific (Hong Kong) | Not available | > | ap-south-1 | Asia Pacific (Mumbai) | Available | > | ap-southeast-1 | Asia Pacific (Singapore) | Available | > | ap-southeast-2 | Asia Pacific (Sydney) | Available | > | ap-northeast-1 | Asia Pacific (Tokyo) | Available | > | ap-northeast-2 | Asia Pacific (Seoul) | Available | **3. Fill In the Required Section** Enter: * **Admin password:** the password for the built-in account `admin@prowler.local`. * **Notification email:** the address that receives update, alarm and subscription notices. * **Lighthouse AI:** whether to turn it on. Leave it off in the Regions where it is not available. * **Portal access:** who can open the portal, from anywhere or only from an IP range. Leave the optional fields and the version as they are, acknowledge the Identity and Access Management (IAM) capabilities, and create the stack. The installation takes about 35 minutes. **4. Confirm the Notification Email** AWS sends a subscription confirmation to the notification address. Confirm it: without it, no update, alarm or subscription notices arrive. **5. Sign In** Open the address in the stack's **Outputs** tab (`UiUrl`), an Amazon CloudFront address until a [custom domain](#updates-and-settings) is set up, and sign in as `admin@prowler.local` with the admin password set in step 3. The AWS account Prowler is installed in is already connected: start its first scan from **Scans**, and invite the team from **Users**. **6. Add Cloud Accounts** From **Cloud Providers** in the portal, add single AWS accounts, a whole AWS Organization, or other providers. ## How Billing Works * **Monthly count:** each cloud account Prowler scans in a calendar month (UTC) counts once that month, however many scans it has. * **AWS bill:** the subscription appears on the AWS bill, line by line, including the accounts the plan includes at 0.00 USD. * **Monthly statement:** at the start of each month, the installation emails last month's usage. If the subscription ends, Prowler keeps working for 7 days and a daily email counts the days down. After that, new scans and premium features pause, but findings, history and reports stay. Subscribing again resumes everything within the hour. ## Updates and Settings New Prowler releases install automatically every night. Settings chosen at launch can be changed later with a stack update: > [accordion] Use a Custom Domain > > Without a custom domain, Prowler runs on its Amazon CloudFront address. > > 1. Choose a subdomain that starts with `prowler`, such as `prowler.example.com`. > 2. Request an AWS Certificate Manager certificate for `cloud.prowler.example.com`, `api.cloud.prowler.example.com` and `mcp.prowler.example.com` in us-east-1. Request a second one in the installation's Region, unless the domain is an Amazon Route 53 hosted zone in the same account. > 3. Open the AWS CloudFormation console in the installation's Region, go to **Stacks**, select the Prowler stack, and click **Update**, then **Make a direct update**. > 4. Choose **Use existing template** and click **Next**. > 5. Fill in the **Your own domain** fields with the domain and the certificates, and leave every other parameter as it is. Click **Next** until the review page. > 6. Acknowledge the IAM capabilities and click **Submit**. > [accordion] Turn Lighthouse AI On or Off > > To turn Lighthouse AI on: > > 1. Open the AWS CloudFormation console in the installation's Region, go to **Stacks**, select the Prowler stack, and click **Update**, then **Make a direct update**. > 2. Choose **Use existing template** and click **Next**. > 3. Set **Lighthouse AI** to **Enabled**, and leave every other parameter as it is. Click **Next** until the review page. > 4. Acknowledge the IAM capabilities and click **Submit**. Lighthouse AI is ready within minutes and needs no keys. > > To turn it off, delete its provider in the portal's Lighthouse AI settings. ## Uninstall Contact [support@prowler.com](mailto:support@prowler.com) for the uninstall steps: the installation protects its data against accidental deletion, so deleting the stack on its own stops partway. Uninstalling does not cancel the subscription; cancel it in the AWS Marketplace console, under **Manage subscriptions**. ## Get Support Write to [support@prowler.com](mailto:support@prowler.com), with the AWS account ID, the Region and the stack name. # Prowler SDK Source: https://docs.prowler.com/getting-started/products/prowler-sdk Prowler SDK is the Python library that powers Prowler CLI and Prowler Local Server. It implements the providers, services, and security checks that every Prowler product runs. To use or extend Prowler SDK, start with the Developer Guide: > [card] [Developer Guide](/developer-guide/introduction) > > Providers, services, checks, and testing: everything needed to work with Prowler SDK. # Introduction Source: https://docs.prowler.com/introduction # What is Prowler? **Prowler** is the world’s most widely used open-source cloud security platform that **automates security and compliance** across any cloud environment. With thousands of ready-to-use security checks, remediation guidance, and compliance frameworks, Prowler delivers AI-driven, customizable, and easy-to-use monitoring and integrations, making cloud security simple, scalable, and cost-effective for organizations of any size. ![](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/products/overview.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=96ceafb0329e6aec90333fa492da83af) > [card] [Get started with Prowler Cloud](https://cloud.prowler.com/sign-up) > > The fastest way to run Prowler: create an account, connect a provider, and get findings without installing anything. No billing details are required during the trial period. Prowler ships two product families: Prowler Products, operated or licensed by the Prowler team, and Open Source projects, free to run and extend. See [Prowler product families](/getting-started/products) for every official name, including former names. ### Prowler Products > [card] [Prowler Cloud](/getting-started/products/prowler-cloud) > > Managed cloud security platform operated by the Prowler team. > [card] [Prowler Hub](/getting-started/products/prowler-hub) > > Free public library of versioned checks, cloud service artifacts, and compliance frameworks. > [card] [Prowler MCP](/getting-started/products/prowler-mcp) > > MCP server that connects AI assistants and agents to Prowler. > [card] [All Prowler Products](/getting-started/products) > > Prowler Private Cloud, Prowler Lighthouse AI, and more. ### Open Source Free to run and extend. Prefer the Open Source projects to run Prowler from a terminal, in CI/CD, or on infrastructure you operate yourself. > [card] [Prowler CLI](/getting-started/products/prowler-cli) > > Command line tool to run security scans across all supported providers. > [card] [Prowler Local Server](/getting-started/products/prowler-app) > > Self-hosted web application and API. ## Supported Providers Prowler supports a wide range of providers organized by category: ### Cloud Service Providers (Infrastructure) | Provider | Support | Audit Scope/Entities | Interface | | - | - | - | - | | [Alibaba Cloud](/user-guide/providers/alibabacloud/getting-started-alibabacloud) | Official | Accounts | UI, API, CLI | | [AWS](/user-guide/providers/aws/getting-started-aws) | Official | Accounts | UI, API, CLI | | [Azure](/user-guide/providers/azure/getting-started-azure) | Official | Subscriptions | UI, API, CLI | | [Cloudflare](/user-guide/providers/cloudflare/getting-started-cloudflare) | Official | Accounts | UI, API, CLI | | [E2E Networks](/user-guide/providers/e2enetworks/getting-started-e2enetworks) | [Contact us](https://prowler.com/contact) | Projects | CLI | | [Google Cloud](/user-guide/providers/gcp/getting-started-gcp) | Official | Projects | UI, API, CLI | | [Huawei Cloud](/user-guide/providers/huaweicloud/getting-started-huaweicloud) | [Contact us](https://prowler.com/contact) | Accounts | CLI | | [Linode](/user-guide/providers/linode/getting-started-linode) | [Contact us](https://prowler.com/contact) | Accounts | CLI | | **NHN** | [Contact us](https://prowler.com/contact) | Tenants | CLI | | [OpenStack](/user-guide/providers/openstack/getting-started-openstack) | Official | Projects | UI, API, CLI | | [Oracle Cloud](/user-guide/providers/oci/getting-started-oci) | Official | Tenancies / Compartments | UI, API, CLI | | [Scaleway](/user-guide/providers/scaleway/getting-started-scaleway) | [Contact us](https://prowler.com/contact) | Organizations | CLI | | [StackIT](/user-guide/providers/stackit/getting-started-stackit) | [Contact us](https://prowler.com/contact) | Projects | CLI | ### Infrastructure as Code Providers | Provider | Support | Audit Scope/Entities | Interface | | - | - | - | - | | [Infra as Code](/user-guide/providers/iac/getting-started-iac) | Official | Repositories | UI, API, CLI | ### Software as a Service (SaaS) Providers | Provider | Support | Audit Scope/Entities | Interface | | - | - | - | - | | [GitHub](/user-guide/providers/github/getting-started-github) | Official | Organizations / Repositories | UI, API, CLI | | [Google Workspace](/user-guide/providers/googleworkspace/getting-started-googleworkspace) | Official | Domains | UI, API, CLI | | [LLM](/user-guide/providers/llm/getting-started-llm) | Official | Models | CLI | | [M365](/user-guide/providers/microsoft365/getting-started-m365) | Official | Tenants | UI, API, CLI | | [MongoDB Atlas](/user-guide/providers/mongodbatlas/getting-started-mongodbatlas) | Official | Organizations | UI, API, CLI | | [Okta](/user-guide/providers/okta/getting-started-okta) | Official | Organizations | UI, API, CLI | | [Vercel](/user-guide/providers/vercel/getting-started-vercel) | Official | Teams / Projects | UI, API, CLI | ### Kubernetes | Provider | Support | Audit Scope/Entities | Interface | | - | - | - | - | | [Kubernetes](/user-guide/providers/kubernetes/getting-started-k8s) | Official | Clusters | UI, API, CLI | ### Containers | Provider | Support | Audit Scope/Entities | Interface | | - | - | - | - | | [Image](/user-guide/providers/image/getting-started-image) | Official | Container Images / Registries | UI, API, CLI | ### Custom Providers (Prowler Private Cloud Only) | Provider | Support | Audit Scope/Entities | Interface | | - | - | - | - | | VMware/Broadcom VCF | Official | Infrastructure | CLI | For more information about the checks and compliance of each provider, visit [Prowler Hub](https://hub.prowler.com). ## Where to Go Next? > [card] [User Guide](/user-guide/tutorials/prowler-app) > > Detailed instructions on how to use Prowler. > [card] [Development Guide](/developer-guide/introduction) > > Interested in contributing to Prowler? # Data Regions & Availability Source: https://docs.prowler.com/security/data-regions Prowler Cloud runs on AWS with high availability built in. ## Regions | Region | URL | Location | | - | - | - | | **EU** | [cloud.prowler.com](https://cloud.prowler.com) | Ireland (`eu-west-1`) | | **US** | On-Demand | On-Demand | ## Business Continuity | Control | Details | | - | - | | **High Availability** | Multi-AZ databases and load-balanced stateless application layer on AWS | | **Disaster Recovery** | Encrypted backups, tested regularly | | **[RPO](https://en.wikipedia.org/wiki/Recovery_point_objective)** | 24 hours | | **[RTO](https://en.wikipedia.org/wiki/Recovery_time_objective)** | 2 hours | | **Status** | [status.prowler.com](https://status.prowler.com) — uptime history and incidents | ## Contact For questions about data regions and availability, visit the [Support page](/support). # Encryption Source: https://docs.prowler.com/security/encryption Prowler Cloud uses encryption everywhere possible. All data and communications are encrypted at rest and in transit. ## Encryption at Rest All data stored in Prowler Cloud is encrypted at rest using AES-256 encryption, including: * **Database contents:** All scan results, findings, and configuration data. * **File storage:** Reports, exports, and uploaded files. * **Backups:** All backup data is encrypted. ## Encryption in Transit All communications with Prowler Cloud are encrypted in transit using TLS 1.2 or higher, including: * **API requests:** All REST API communications. * **Web application traffic:** Browser-to-server connections. * **Internal service communication:** Service-to-service traffic within the platform. ## Contact For questions regarding encryption, visit the [Support page](/support). # Security & Compliance Source: https://docs.prowler.com/security/index **Prowler secures itself with Prowler.** As an open-source cloud security platform trusted by thousands of organizations, Prowler applies the same rigorous security standards internally that customers achieve externally. All security tooling, configurations, and CI/CD pipelines are publicly available in the [Prowler GitHub repository](https://github.com/prowler-cloud/prowler). Transparency is fundamental to open-source security. ## Software Security All Prowler code goes through the same security pipeline, whether running on Prowler Cloud or self-managed infrastructure: DAST, SAST, SCA, container scanning, and secrets detection on every build. > [card] [Software Security](/security/software-security) > > Security tools and practices applied to all Prowler code. ## Prowler Cloud vs Prowler OSS (Self-Managed) | | Prowler Cloud | Self-Managed | | - | - | - | | **Deployment** | Fully managed SaaS | Own infrastructure | | **Region** | EU (Ireland) | Any region or provider | | **Compliance** | SOC 2 Type II, AWS FTR | Organization responsibility | | **Data Control** | Prowler managed | Full control | | **Encryption** | AES-256 at rest, TLS 1.2+ in transit | Configurable | | **Backups** | Automated | Organization responsibility | | **Updates** | Automatic | Manual | > [!NOTE] > > Self-Managed includes Prowler Local Server and Prowler CLI. They can run anywhere — any cloud provider, any region, on-premises, or air-gapped environments. Full control over data residency and infrastructure decisions. See the [Prowler Local Server Installation Guide](/getting-started/installation/prowler-app) to get started. *** ## Prowler Cloud This section covers security and compliance for **Prowler Cloud**, the managed infrastructure. ### Trust & Compliance Prowler Cloud holds compliance certifications and undergoes regular audits. | Certification | Status | | - | - | | **SOC 2 Type II** | [View on Trust Portal](https://trust.prowler.com) | | **AWS Foundational Technical Review (FTR)** | Passed — [Details](https://aws.amazon.com/partners/foundational-technical-review/) | Compliance data and reports: [trust.prowler.com](https://trust.prowler.com) ### Security > [card] [Encryption](/security/encryption) > > Data encrypted at rest (AES-256) and in transit (TLS 1.2+). > [card] [Data Regions](/security/data-regions) > > EU-hosted infrastructure with high availability and disaster recovery. > [card] [Networking](/security/networking) > > Static egress IPs for firewall allowlisting. ### Privacy Prowler Cloud is GDPR compliant in regard to the ["right to be forgotten"](https://gdpr.eu/right-to-be-forgotten/). When an account is deleted, user information is removed from online and backup systems within 10 calendar days. *** ## Report a Vulnerability Found a security issue? Report it through the [responsible disclosure](https://prowler.com/.well-known/security.txt) process. ## Contact For security inquiries or general support, visit the [Support page](/support). # Networking Source: https://docs.prowler.com/security/networking ## Egress IP Addresses Prowler Cloud makes outbound API calls to scan cloud provider accounts and connect to integrations. Allowlist these IPs in firewalls or security groups to restrict access to Prowler Cloud only. | Region | IP Address | | - | - | | EU (Ireland) | `52.48.254.174` | Resolve the egress IP via DNS: ```bash theme={null} dig egress.prowler.com +short ``` > [!NOTE] > > The egress IP address is stable, but it is recommended to periodically verify it remains current by querying `egress.prowler.com`. ## Use Cases Allowlisting Prowler Cloud's egress IP address enables: * **Credential Usage Control**: Restrict where cloud provider credentials can be used from across AWS, Azure, GCP, and other providers * **Kubernetes Security**: Limit inbound HTTPS traffic to clusters by allowing only Prowler Cloud's IP address * **Compliance Requirements**: Meet security policies requiring allowlisting of external services ## Contact For questions about networking, visit the [Support page](/support). # Software Security Source: https://docs.prowler.com/security/software-security Prowler applies security-by-design across the development lifecycle. Every change passes automated checks at each stage: pre-commit hooks locally, multiple CI gates on pull requests, branch protection before merge, container scanning before publish, and registry monitoring after release. All security tooling and configuration lives in the [Prowler GitHub repository](https://github.com/prowler-cloud/prowler): [pre-commit hooks](https://github.com/prowler-cloud/prowler/blob/master/.pre-commit-config.yaml), [CI/CD workflows](https://github.com/prowler-cloud/prowler/tree/master/.github/workflows), and [Dependabot configuration](https://github.com/prowler-cloud/prowler/blob/master/.github/dependabot.yml). ## Coverage Security controls cover six domains, each detailed below: | Domain | What It Protects | | - | - | | [**CI/CD**](#cicd-security) | GitHub Actions workflows, runners, third-party actions | | [**SAST**](#static-application-security-testing-sast) | Application source code | | [**SCA**](#software-composition-analysis-sca) | Third-party dependencies and their known vulnerabilities | | [**Supply-Chain Pinning**](#supply-chain-pinning) | Reproducible installs across Python, npm, GitHub Actions, container base images | | [**Containers**](#container-security) | Runtime images for UI, API, SDK, Model Context Protocol (MCP) Server | | [**Secrets**](#secrets-detection) | Credentials, tokens, API keys in code and git history | ## CI/CD Security Every GitHub Actions workflow uses runner hardening, pinned action versions, and audited permissions. ### Runner Hardening With StepSecurity * [**`step-security/harden-runner`**](https://github.com/step-security/harden-runner) runs as the first step in every workflow, pinned by commit SHA. * Workflows are being migrated to explicit egress controls: some already declare an egress allow-list with `egress-policy: block`, while others still run in `egress-policy: audit` until their allowed endpoints are fully defined. * **Global Block Policy** (StepSecurity) blocks known-malicious domains and IP addresses across every workflow run. This protection applies even in audit mode, so workflows that have not yet moved to `block` still resist known-bad egress. ### Third-Party Action Pinning * Every third-party action reference uses a commit SHA with the version as a comment: `uses: org/action@ # v1.2.3`. * Dependabot tracks the comment and proposes SHA-pinned upgrades on a monthly cadence. ### Workflow Permissions * Workflows declare `permissions: {}` at the top level and grant the minimum required scopes per job. * Code review covers permission changes; zizmor enforces the rules (see below). ### Workflow Security Audit With Zizmor * **[zizmor](https://github.com/zizmorcore/zizmor)** audits every workflow file for known security anti-patterns. Runs on every pull request and push. * Triggers on every push, every pull request that touches `.github/`, and on a daily schedule. * Results upload to the GitHub Security tab via Static Analysis Results Interchange Format (SARIF). * Key [audit rules](https://docs.zizmor.sh/audits/) the build gates on: * **[PWN Request](https://docs.zizmor.sh/audits/#dangerous-triggers)** (`dangerous-triggers`): unsafe use of `pull_request_target` with checked-out PR code. * **[Script Injection](https://docs.zizmor.sh/audits/#template-injection)** (`template-injection`): unsanitized `${{ github.event.* }}` expressions in `run:` blocks. * **[artipacked](https://docs.zizmor.sh/audits/#artipacked)**: credential leakage through artifacts. * **[Excessive permissions](https://docs.zizmor.sh/audits/#excessive-permissions)** (`excessive-permissions`): workflows with unneeded `write` scopes. ### Branch Protection Pull requests to `master` and the active `v5.*` release branches must pass several required workflows before merge. These gates prevent specific classes of supply-chain and pipeline attacks from reaching the main branch: * **Compromised packages:** the **npm Package Compromised Updates** and **PyPI Package Compromised Updates** checks (StepSecurity) fail any PR that introduces a package version present in the compromised-package feed. Layered on top of osv-scanner. * **Premature releases:** the **npm Package Cooldown** and **PyPI Package Cooldown** checks (StepSecurity) fail any PR that introduces a package version published within the cooldown window. Layered on top of pnpm's `minimumReleaseAge`. * **Workflow exploitation:** the **PWN Request** and **Script Injection** checks (StepSecurity) reject the corresponding zizmor-detected anti-patterns at PR time. Layered on top of zizmor's audit. * **Vulnerable code or dependencies:** CodeQL (UI, API, SDK), osv-scanner (SDK, API, UI), Bandit (SDK, API), and Trivy (container images) must all pass. ## Static Application Security Testing (SAST) Multiple SAST tools run on every push and pull request to catch vulnerabilities and code-quality issues before merge. ### Cross-Language * **CodeQL:** semantic code analysis for the UI (JavaScript/TypeScript), API (Python), and SDK (Python). Runs on every push and pull request, plus a daily scheduled scan. Results upload to the GitHub Security tab via SARIF. ### Python (SDK + API) * **Bandit:** detects common Python security issues (SQL injection, hardcoded credentials, insecure deserialization). Runs in pre-commit and on every pull request and push. * **Pylint:** analyzes your code without actually running it. It checks for errors, enforces a coding standard, looks for code smells, and can suggest refactors. Runs in pre-commit and on every pull request and push. * **Vulture:** dead-code detection at `--min-confidence 100`. Unused code can hide incomplete implementations or stale security paths. Runs in pre-commit and on every pull request and push. * **Flake8:** style and correctness checks for the SDK. Runs in pre-commit and on every pull request and push. ### JavaScript/TypeScript (UI) * **TypeScript (`tsc`):** strict type checking for the UI. Catches whole classes of null/undefined and type-confusion bugs at build time. Runs on every pull request and push via `pnpm run healthcheck`. * **ESLint:** UI linting with a capped warning budget (`--max-warnings 40`). Runs on every pull request and push via `pnpm run healthcheck`. * **Knip:** dead-code and unused-export detection for the UI. The UI analogue to Vulture. > [!NOTE] > > Knip runs locally on demand via `pnpm run lint:knip` and is not yet wired into CI. ### Shell * **Shellcheck:** correctness and security checks for shell scripts in `.github/scripts/` and `scripts/`. Runs in pre-commit on staged files. ## Software Composition Analysis (SCA) Dependencies are scanned against public vulnerability databases on every pull request and push, with results posted directly on the PR. ### Cross-Language * **osv-scanner:** scans lockfiles against the [OSV.dev](https://osv.dev) vulnerability database for SDK (`uv.lock`), API (`api/uv.lock`), and UI (`ui/pnpm-lock.yaml`). Runs on every pull request and push. * The action installs the `osv-scanner` binary and verifies its SHA-256 checksum against the upstream-signed `SHA256SUMS` manifest before running. Any mismatch aborts the scan. * Gates the build on `HIGH`, `CRITICAL`, and `UNKNOWN` severity findings. * Posts and updates a per-lockfile report as a pull request comment. * Per-vulnerability ignores live in [`osv-scanner.toml`](https://github.com/prowler-cloud/prowler/blob/master/osv-scanner.toml) at the repo root, each with a reason and an expiry date. * **Trivy:** scans container images for OS-package and application-dependency vulnerabilities. Runs on every pull request and push that touches an image or its dependencies. Trivy uploads SARIF to the GitHub Security tab and posts a scan summary on the PR. * **Dependabot:** [configured](https://github.com/prowler-cloud/prowler/blob/master/.github/dependabot.yml) for monthly updates of the SDK Python dependencies, GitHub Actions, Docker base images, and pre-commit hooks. Dependabot opens pull requests for known security advisories, so critical patches reach the team without delay. A 7-day default cooldown reduces exposure to compromised package releases. * **Renovate:** [configured](https://github.com/prowler-cloud/prowler/blob/master/.github/renovate.json) dependency update automation is transitioning from Dependabot to **Renovate** to gain finer control over update cadence, grouping, and per-component scope. Both tools currently run in parallel during the migration. #### Renovate (Primary) Configuration: [`.github/renovate.json`](https://github.com/prowler-cloud/prowler/blob/master/.github/renovate.json) * **Coverage:** Python (SDK, API, MCP Server), npm (UI), GitHub Actions, Docker images, and Pre-commit hooks * **Range Strategy:** Versions are pinned to ensure reproducible builds * **Vulnerability Alerts:** GitHub Security Advisories generate immediate pull requests that bypass rate limits and scheduled windows, labeled `security` for prioritized triage #### Dependabot (Legacy) Configuration: [`.github/dependabot.yml`](https://github.com/prowler-cloud/prowler/blob/master/.github/dependabot.yml) Dependabot remains active for the SDK and shared automation ecosystems until the Renovate migration completes: * **Python (pip):** Monthly updates for SDK * **GitHub Actions:** Monthly updates for workflow dependencies * **Docker:** Monthly updates for base images * **Pre-commit:** Monthly updates for hook revisions Dependabot is paused for the API and UI; Renovate now handles those components. Even when paused, Dependabot continues to open pull requests for security vulnerabilities, ensuring critical patches are never delayed. ### JavaScript/TypeScript (UI) * **pnpm audit:** runs `pnpm audit --audit-level critical` on every UI pull request and push as part of `pnpm run audit`. Cross-checks the npm registry's advisory database in addition to the OSV scan and surfaces npm-specific advisories that may not yet have an OSV identifier. ## Supply-Chain Pinning Pinning runs across Python, npm, GitHub Actions, and container base images. Every install resolves to the exact set of versions already vetted in CI, and any drift fails loudly instead of slipping in silently. ### Python (uv) The SDK, API, and MCP Server all use [uv](https://docs.astral.sh/uv/) for dependency management. Each component has its own project manifest and lock file: | Component | Manifest | Lock File | | - | - | - | | SDK | `pyproject.toml` | `uv.lock` | | API | `api/pyproject.toml` | `api/uv.lock` | | MCP Server | `mcp_server/pyproject.toml` | `mcp_server/uv.lock` | The controls applied across all three: * **Direct dependencies pinned to exact versions** (`==`). No version ranges in dependency lists. * **Transitive dependencies pinned** via `[tool.uv].constraint-dependencies` in the SDK and API manifests. The constraint set mirrors the versions locked in the corresponding `uv.lock`. A future `uv lock` preserves these versions instead of silently picking up newer releases, and the resolver fails when a constraint becomes infeasible, signaling that a deliberate bump is needed. * **Lock files committed.** CI installs strictly from the lock. * **uv itself pinned** in the [`setup-python-uv`](https://github.com/prowler-cloud/prowler/tree/master/.github/actions/setup-python-uv) composite action. > [!NOTE] > > The MCP Server declares a small constraint set of its own, covering transitive pins that `fastmcp` does not raise on its own. Its lock file remains the source of truth for everything else. ### JavaScript/TypeScript (pnpm) The UI uses [pnpm](https://pnpm.io) with supply-chain controls configured in [`ui/pnpm-workspace.yaml`](https://github.com/prowler-cloud/prowler/blob/master/ui/pnpm-workspace.yaml). * **Minimum release age** (`minimumReleaseAge: 1440`): packages must publish at least 24 hours before install. This reduces exposure during the window when a compromised release has not yet been detected and yanked. * **Lifecycle script allow-list** (`strictDepBuilds: true` + `allowBuilds`): only explicitly approved packages may run `install` or `postinstall` scripts (currently `sharp`, `esbuild`, `@sentry/cli`, `unrs-resolver`, `msw`). Any unlisted package with lifecycle scripts fails the install. * **Trust policy** (`trustPolicy: no-downgrade`): the install fails when a package's trust evidence drops, for example after a new publisher takes over. * **Block exotic subdeps** (`blockExoticSubdeps: true`): transitive dependencies cannot ship as git URLs or tarballs. Every package in the tree resolves from the configured registry. * **Transitive overrides** in [`ui/package.json`](https://github.com/prowler-cloud/prowler/blob/master/ui/package.json) force specific versions for transitive packages (`lodash`, `serialize-javascript`, `qs`, `rollup`, `minimatch`, `ajv`, and others). * **`pnpm-lock.yaml` committed** and CI installs strictly from the lock. * **pnpm itself pinned** via the `packageManager` field in `package.json` with an integrity hash. ### GitHub Actions * Every third-party action reference uses a commit SHA, with the version in a trailing comment. * Dependabot opens monthly PRs to bump pinned SHAs. ### Container Base Images * Every Dockerfile references base images by digest (`image@sha256:...`). * Dependabot opens monthly PRs to bump digests. ## Container Security Container images get scanned twice: once in CI before they push to a registry, and continuously after publish by the registries themselves. ### Pre-Publish (CI) * **Trivy** scans for OS-package and application-dependency vulnerabilities. Runs on every pull request and push that touches an image or its dependencies. Trivy uploads SARIF to the GitHub Security tab and posts a summary on the PR. Builds fail on any critical finding that is not explicitly accepted. Accepted findings live in [`.trivyignore.yaml`](https://github.com/prowler-cloud/prowler/blob/master/.trivyignore.yaml), each carrying a reason and an expiry date, the same policy `osv-scanner.toml` follows. A local `trivy image` run does not apply these suppressions unless you pass `--ignorefile .trivyignore.yaml`: Trivy auto-loads only the classic `.trivyignore` format, never the YAML one. * **Hadolint** validates Dockerfile syntax and structure against secure-build best practices. Runs in pre-commit and alongside the image scans above. ### Post-Publish (Registries) * **Amazon ECR:** ECR continuously scans published images for vulnerabilities. New advisories disclosed after publish surface on the image without requiring a rebuild. * **Docker Hub:** Docker Hub continuously scans the same images mirrored from ECR. * The security team reviews findings from both registries for triage and remediation. ### Known Findings A small number of findings remain in the published images and cannot be resolved by Prowler: the upstream project has released no fix, the package cannot be removed without breaking the image, or the finding comes from a vendored SBOM rather than from a package that is actually installed. Alternative base distributions have been evaluated and none currently satisfies both the vulnerability profile and the runtime requirements of every supported provider. Each suppression is recorded in [`.trivyignore.yaml`](https://github.com/prowler-cloud/prowler/blob/master/.trivyignore.yaml) with the reason it cannot be fixed, why it is not exploitable in Prowler's runtime, and an expiry date that forces re-review. Nothing is suppressed without that rationale, and a build fails on any critical finding that is not listed there. To see the current set for any image, scan it directly. This reports everything, including the accepted findings above, because Trivy does not read `.trivyignore.yaml` unless it is named: ```bash theme={null} trivy image prowlercloud/prowler:latest ``` To see only what is *not* already accepted, point Trivy at the suppression file: ```bash theme={null} trivy image --ignorefile .trivyignore.yaml prowlercloud/prowler:latest ``` ## Secrets Detection * **[TruffleHog](https://github.com/trufflesecurity/trufflehog)** scans the codebase and git history on every push and pull request. Detects high-entropy strings, API keys, tokens, and credentials, and reports verified and unknown findings. * A pre-commit hook runs the same check locally and blocks secrets before they leave the developer machine. ## Security Monitoring * **GitHub Security tab:** centralized view of findings from CodeQL, Trivy, zizmor, and any other SARIF-compatible tool. * **PR comments:** osv-scanner and Trivy post per-PR summaries so issues surface during review, not after merge. * **Artifact retention:** the build retains security scan reports for post-deployment analysis. ## Contact For questions about software security, see the [Support page](/support). To report a vulnerability, follow the [responsible disclosure process](https://prowler.com/.well-known/security.txt). # Support Source: https://docs.prowler.com/support Get help with Prowler ## Prowler Lighthouse AI Prowler Lighthouse AI is your 24/7 cloud security analyst chatbot, the agentic cloud defender. Powered by [Prowler MCP](/getting-started/products/prowler-mcp), it can: * **Query your security data**: Findings, compliance status, resources, and remediation guidance * **Search Prowler Hub**: Over 2,000 security checks and 70+ compliance frameworks * **Access documentation**: Search and retrieve Prowler docs contextually Available in Prowler Cloud, Prowler Private Cloud, and Prowler Local Server. [Learn more about Prowler Lighthouse AI](/getting-started/products/prowler-cloud-lighthouse) ## Support Desk > [!NOTE] > > This service is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). Submit support requests through our support desk. We'll route your request to the right team and respond via email. > [card] [Submit a request](https://support.prowler.com) > > Contact our support team ## GitHub Discussions Prowler is Open Source. If you have a question, it's likely someone else has it too. We'd love to answer in the open on GitHub whenever possible. > [card] [Ask a question](https://github.com/prowler-cloud/prowler/discussions) > > Get help from the community > [card] [Report a bug](https://github.com/prowler-cloud/prowler/issues/new?template=bug_report.yml) > > Found something wrong? Let us know > [card] [Suggest a feature](https://github.com/prowler-cloud/prowler/issues/new?template=feature-request.yml) > > Share your ideas for improvements ## Community Slack Join our Slack workspace to connect with the Prowler community, ask questions, and get help from other users and the Prowler team. > [card] [Join Prowler Slack](https://goto.prowler.com/slack) > > Connect with the community ## Office Hours Join our open calls to discuss what you're building, ask questions, and connect with the Prowler team and community. Office Hours sessions are announced on [LinkedIn](https://www.linkedin.com/company/prowler-security/). Recordings of previous sessions are available on [YouTube](https://www.youtube.com/playlist?list=PLIwvjRXuMGkE-BDYXmUR2TXYQ7agxtuB1). ## Security To report a vulnerability or for security-related inquiries, contact [security@prowler.com](mailto:security@prowler.com). See also: [Responsible Disclosure](https://prowler.com/.well-known/security.txt) # Troubleshooting Source: https://docs.prowler.com/troubleshooting ## Prowler CLI ### Running `prowler` I get `[File: utils.py:15] [Module: utils] CRITICAL: path/redacted: OSError[13]` That is an error related to file descriptors or opened files allowed by your operating system. In macOS Ventura, the default value for the `file descriptors` is `256`. With the following command `ulimit -n 1000` you'll increase that value and solve the issue. If you have a different OS and you are experiencing the same, please increase the value of your `file descriptors`. You can check it running `ulimit -a | grep "file descriptors"`. This error is also related with a lack of system requirements. To improve performance, Prowler stores information in memory so it may need to be run in a system with more than 1GB of memory. See section [Logging](/user-guide/cli/tutorials/logging) for further information or [contact us](/contact). ## Prowler Local Server Common issues with the Docker Compose installation of Prowler Local Server. ### Problem Adding AWS Provider Using "Connect assuming IAM Role" in Docker See [GitHub Issue #7745](https://github.com/prowler-cloud/prowler/issues/7745) for more details. When running Prowler Local Server via Docker, you may encounter errors such as `Provider not set`, `AWS assume role error - Unable to locate credentials`, or `Provider has no secret` when trying to add an AWS Provider using the "Connect assuming IAM Role" option. This typically happens because the container does not have access to the necessary AWS credentials or profiles. **Workaround:** * Ensure your AWS credentials and configuration are available to the Docker container. You can do this by mounting your local `.aws` directory into the container. For example, in your `docker-compose.yaml`, add the following volume to the relevant services: ```yaml theme={null} volumes: - "${HOME}/.aws:/home/prowler/.aws:ro" ``` This should be added to the `api`, `worker`, and `worker-beat` services. * Create or update your `~/.aws/config` and `~/.aws/credentials` files with the appropriate profiles and roles. For example: ```ini theme={null} [profile prowler-profile] role_arn = arn:aws:iam:::role/ProwlerScan source_profile = default ``` And set the environment variable in your `.env` file: ```env theme={null} AWS_PROFILE=prowler-profile ``` * If you are scanning multiple AWS accounts, you may need to add multiple profiles to your AWS config. Note that this workaround is mainly for local testing; for production or multi-account setups, follow the [CloudFormation Template guide](https://github.com/prowler-cloud/prowler/issues/7745) and ensure the correct IAM roles and permissions are set up in each account. ### Scans Complete but Reports Are Missing or Compliance Data Is Empty (`Too many open files` Error) When running Prowler Local Server via Docker Compose, scans may complete successfully but reports are not available for download, compliance data shows as empty, or 404 errors appear when trying to access scan reports. Checking the `worker` container logs may reveal errors like `[Errno 24] Too many open files`. This issue occurs because the default file descriptor limits in Docker containers are too low for Prowler's operations. The default `docker-compose.yml` already includes `ulimits` configuration with `nofile` set to `65536` for the `worker` and `worker-beat` services to prevent this issue. If a custom `docker-compose.yml` is being used or the default configuration has been modified, ensure the `ulimits` configuration is present in both the `worker` and `worker-beat` services: ```yaml theme={null} services: worker: ulimits: nofile: soft: 65536 hard: 65536 # ... rest of service configuration worker-beat: ulimits: nofile: soft: 65536 hard: 65536 # ... rest of service configuration ``` After making these changes, restart the Docker Compose stack: ```bash theme={null} docker compose down docker compose up -d ``` ### Worker Uses Too Much Memory on Hosts with Many CPUs [Added in:  5.31.0](https://github.com/prowler-cloud/prowler/releases/tag/5.31.0) When Prowler Local Server runs on a machine or Kubernetes node with many CPUs, the Celery worker may create one prefork process per detected CPU if concurrency is not configured explicitly. Each process loads the SDK runtime and cloud provider clients, so idle memory can be high and worker containers can be terminated by their memory limit. Set `DJANGO_CELERY_WORKER_CONCURRENCY` in the worker runtime environment to cap the number of prefork processes: ```yaml theme={null} services: worker: environment: DJANGO_CELERY_WORKER_CONCURRENCY: "4" ``` For Kubernetes deployments, set the same variable on the worker Deployment: ```yaml theme={null} env: - name: DJANGO_CELERY_WORKER_CONCURRENCY value: "4" ``` Lower values reduce idle memory and the number of tasks a worker can run in parallel. Increase the value only when the worker has enough memory for the expected scan workload. Leaving the variable unset preserves Celery's default CPU-based concurrency. ### API Container Fails to Start with JWT Key Permission Error See [GitHub Issue #8897](https://github.com/prowler-cloud/prowler/issues/8897) for more details. When deploying Prowler via Docker Compose on a fresh installation, the API container may fail to start with permission errors related to JWT RSA key file generation. This issue is commonly observed on Linux systems (Ubuntu, Debian, cloud VMs) and Windows with Docker Desktop, but not typically on macOS. **Error Message:** Checking the API container logs reveals: ```bash theme={null} PermissionError: [Errno 13] Permission denied: '/home/prowler/.config/prowler-api/jwt_private.pem' ``` Or: ```bash theme={null} Token generation failed due to invalid key configuration. Provide valid DJANGO_TOKEN_SIGNING_KEY and DJANGO_TOKEN_VERIFYING_KEY in the environment. ``` **Root Cause:** This permission mismatch occurs due to UID (User ID) mapping between the host system and Docker containers: * The API container runs as user `prowler` with UID/GID 1000 * In environments like WSL2, the host user may have a different UID than the container user * Docker creates the mounted volume directory `./_data/api` on the host, often with the host user's UID or root ownership (UID 0) * When the application attempts to write JWT key files (`jwt_private.pem` and `jwt_public.pem`), the operation fails because the container's UID 1000 does not have write permissions to the host-owned directory **Solutions:** There are two approaches to resolve this issue: **Option 1: Fix Volume Ownership (Resolve UID Mapping)** Change the ownership of the volume directory to match the container user's UID (1000): ```bash theme={null} # The container user 'prowler' has UID 1000 # This command changes the directory ownership to UID 1000 sudo chown -R 1000:1000 ./_data/api ``` Then start Docker Compose: ```bash theme={null} docker compose up -d ``` This solution directly addresses the UID mapping mismatch by ensuring the volume directory is owned by the same UID that the container process uses. **Option 2: Use Environment Variables (Skip File Storage)** Generate JWT RSA keys manually and provide them via environment variables to bypass file-based key storage entirely: ```bash theme={null} # Generate RSA keys openssl genrsa -out jwt_private.pem 4096 openssl rsa -in jwt_private.pem -pubout -out jwt_public.pem # Extract key content (removes headers/footers and newlines) PRIVATE_KEY=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' jwt_private.pem) PUBLIC_KEY=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' jwt_public.pem) ``` Add the following to the `.env` file: ```env theme={null} DJANGO_TOKEN_SIGNING_KEY= DJANGO_TOKEN_VERIFYING_KEY= ``` When these environment variables are set, the API will use them directly instead of attempting to write key files to the mounted volume. > [!NOTE] > > A fix addressing this permission issue is being evaluated in [PR #9953](https://github.com/prowler-cloud/prowler/pull/9953). ### Scan Stuck in Executing State After Worker Crash When running Prowler Local Server via Docker Compose, a scan may remain indefinitely in the `executing` state if the worker process crashes (for example, due to an Out of Memory condition) before it can update the scan status. Since it is not currently possible to cancel a scan in `executing` state through the UI, the workaround is to manually update the scan record in the database. **Root Cause:** The Celery worker process terminates unexpectedly (OOM, node failure, etc.) before transitioning the scan state to `completed` or `failed`. The scan record remains in `executing` with no active process to advance it. **Solution:** Connect to the database using the `prowler_admin` user. Due to Row-Level Security (RLS), the default database user cannot see scan records — you must use `prowler_admin`: ```bash theme={null} psql -U prowler_admin -d prowler_db ``` Identify the stuck scan by filtering for scans in `executing` state: ```sql theme={null} SELECT id, name, state, started_at FROM scans WHERE state = 'executing'; ``` Update the scan state to `failed` using the scan ID: ```sql theme={null} UPDATE scans SET state = 'failed' WHERE id = ''; ``` After this change, the scan will appear as failed in the UI and you can launch a new scan. > [!NOTE] > > A feature to cancel executing scans directly from the UI is being tracked in [GitHub Issue #6893](https://github.com/prowler-cloud/prowler/issues/6893). ### SAML/OAuth ACS URL Incorrect When Running Behind a Proxy or Load Balancer See [GitHub Issue #9724](https://github.com/prowler-cloud/prowler/issues/9724) for more details. When running Prowler behind a reverse proxy (nginx, Traefik, etc.) or load balancer, the SAML ACS (Assertion Consumer Service) URL or OAuth callback URLs may be incorrectly generated using the internal container hostname (e.g., `http://prowler-api:8080/...`) instead of your external domain URL (e.g., `https://prowler.example.com/...`). **Root Cause:** The API base and docs URLs are resolved from the container environment **at runtime**. A single pre-built Docker image (`prowlercloud/prowler-ui:stable`) therefore serves any environment: point the URLs at your external domain and restart the container — no rebuild is required. **Solution:** Set the runtime environment variables to your external URL and restart the UI container: ```yaml theme={null} services: ui: image: prowlercloud/prowler-ui:stable environment: UI_API_BASE_URL: https://prowler.example.com/api/v1 UI_API_DOCS_URL: https://prowler.example.com/api/v1/docs # ... rest of configuration ``` The same values can be supplied through your `.env` file: ```bash theme={null} UI_API_BASE_URL=https://prowler.example.com/api/v1 UI_API_DOCS_URL=https://prowler.example.com/api/v1/docs ``` > [!NOTE] > > Earlier releases inlined these values into the JavaScript bundle at build time (via the `NEXT_PUBLIC_` prefix) and required a rebuild with `--build-arg`. That is no longer necessary: `UI_API_BASE_URL` and `UI_API_DOCS_URL` are read at container start, so updating them and restarting is sufficient. # Connect Claude Code to Prowler MCP Server Source: https://docs.prowler.com/user-guide/ai-agents/claude-code Connect [Claude Code](https://www.claude.com/product/claude-code) to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp`. ## Where Claude Code Runs Claude Code runs in two places. Both read the same configuration file, so you set it up **once from a terminal** and it works in both. | Surface | How you open it | Reads | Covered by | | - | - | - | - | | **Claude Code CLI** | `claude` in a terminal | `~/.claude.json` | This guide | | **Claude Code in the desktop app** | The **Code** tab inside the Claude app | `~/.claude.json` — the same file | This guide, [set up from a terminal](#claude-code-in-the-desktop-app-code-tab) | | **Claude app Chat** | The **Chat** tab inside the Claude app | `claude_desktop_config.json` | [Claude App Chat](/user-guide/ai-agents/claude-desktop) — a separate setup | > [!WARNING] > > **The Chat tab is not Claude Code.** It is a different product surface with its own configuration file and its own connection method (a local bridge). Nothing on this page applies to it. If you want Prowler in Chat, use the [Claude App Chat](/user-guide/ai-agents/claude-desktop) guide instead. ## Choose Your Setup There are two ways to connect. Both end with the same MCP Server connection, the difference is what comes with it. | | 🔌 **Prowler Plugin** | ⚙️ **MCP Connection Only** | | - | - | - | | **What you get** | The MCP connection **plus** the official Prowler skills for cloud security tasks | The MCP connection | | **Setup** | Add it from the [Claude directory](https://claude.ai/directory/prowler-cloud-for-claude-code), or run two slash commands. Prompts for the API key | One `claude mcp add` command | | **Guided workflows** | ✅ Skills drive multi-step security work end to end | ❌ You drive the conversation | | **Best for** | Structured cloud security work, such as taking an account to compliance | Ad-hoc queries and your own workflows | | **Where to use it** | Claude Code CLI | Claude Code CLI, and the **recommended setup for the desktop app's [Code tab](#claude-code-in-the-desktop-app-code-tab)** | > [!NOTE] > > **The plugin already includes the MCP connection.** If you install the plugin, do **not** also run `claude mcp add` — you would end up with the server configured twice. ## Prerequisites * **Claude Code** installed and signed in. See the [official install guide](https://www.claude.com/product/claude-code). * **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). ## Get Your Prowler API Key Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. *** # Option 1: Install the Prowler Plugin > [!WARNING] > > **Preview**: this plugin is under active development. Please report issues on [GitHub](https://github.com/prowler-cloud/prowler/issues) or join the [Slack community](https://goto.prowler.com/slack) for feedback. End-to-end cloud security from inside Claude Code, powered by the Prowler MCP server. The plugin bundles the official Prowler skills, task-specific workflows that let Claude carry out multi-step security work against a Prowler Cloud-connected account, rather than answering one question at a time. ### Included Skills | Skill | What it does | | - | - | | `prowler:framework-compliance-triage` | Walks an account through a compliance assessment and remediates findings until the chosen security or industry framework is compliant. | > [!NOTE] > > More skills are on the way. Installing the plugin keeps you current — new skills arrive with plugin updates, no extra configuration required. ## Installation Prowler Cloud is listed in the official [Claude directory](https://claude.ai/directory/prowler-cloud-for-claude-code). Installing from the directory is the preferred method. > [tab] From the Claude directory (recommended) > > 1. Open the [Prowler Cloud listing](https://claude.ai/directory/prowler-cloud-for-claude-code) in the Claude directory. You can also find it in Claude under **Customize > Plugins > Discover** by searching for **Prowler Cloud**. > 2. Select **Add**. > [tab] From GitHub > > Inside a Claude Code session: > > ```text theme={null} > /plugin marketplace add prowler-cloud/prowler > /plugin install prowler@prowler-plugins > ``` > [tab] From a local clone > > If you already have the repository checked out: > > ```text theme={null} > /plugin marketplace add /absolute/path/to/prowler > /plugin install prowler@prowler-plugins > ``` On first install, Claude Code prompts for your [**Prowler API key**](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys). The value is stored securely (macOS keychain or `~/.claude/.credentials.json`) and used to authenticate against Prowler Cloud. ## Verify the Installation In a Claude Code session: ```text theme={null} /mcp → "prowler" appears as a connected server /plugin → "prowler" enabled, with the bundled Prowler skills listed ``` If `/mcp` reports the `prowler` server as failed, the most common cause is a rejected API key, re-issue one in Prowler Cloud and reinstall the plugin so it re-prompts. ## Usage Describe the security task you want done and Claude selects the matching skill. ### Framework Compliance Triage Mention the framework you want to comply with: * *"Make my AWS production account compliant with CIS 4.0."* * *"Make my current Terraform project compliant with Prowler ThreatScore Compliance Framework based on the latest scan results."* * *"Help me get to 100% on PCI-DSS for this GCP project."* You pick a **primary tool** (Terraform, gh / az / aws CLI, web console, or mixed) and a **mode**: > [card] Claude-assisted (default) > > Claude shows each fix — target resource, exact commands, side effects, reversibility — and waits for your go-ahead before applying. > [card] Claude autonomous > > Claude presents a single up-front plan grouped by shared fixes, waits for one confirmation, then proceeds. It pauses mid-loop if a fix has wide blast radius or a finding is not applicable. Claude tracks progress in a markdown report under `.prowler/` at your project root — one file per framework × account. Open it any time to see exactly where the flow is. When all findings are addressed, Claude proposes a fresh Prowler scan to verify everything end-to-end. ## Uninstalling If you installed the plugin from GitHub or a local clone, run: ```text theme={null} /plugin uninstall prowler@prowler-plugins /plugin marketplace remove prowler-plugins ``` The stored API key is removed automatically. *** # Option 2: Connect the MCP Server Only Choose this when you want Prowler's tools available without the Prowler skills. ## Add the Server Claude Code connects to remote HTTP MCP servers natively and supports custom headers, so no bridge is required. ```bash theme={null} export PROWLER_API_KEY="pk_your_api_key_here" claude mcp add --transport http prowler https://mcp.prowler.com/mcp \ --header "Authorization: Bearer $PROWLER_API_KEY" \ --scope user ``` ![Terminal showing the claude mcp add command and its confirmation output](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/claude/claude-code-mcp-add.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=6c52e90172aa1bc12e50421cd9abb09b) > [!WARNING] > > **Always pass `--scope user`.** The default scope is `local`, which binds the server to the single directory you ran the command in. A locally-scoped server does not load when you open Claude Code anywhere else — this is the most common reason Prowler tools appear to vanish. | Scope | Loads in | Shared | Stored in | | - | - | - | - | | `user` | All your projects | No | `~/.claude.json`, top-level `mcpServers` | | `project` | Current project only | Yes, via version control | `.mcp.json` in the project root | | `local` (default) | Current project only | No | `~/.claude.json`, under that project's entry | When the same server name exists in more than one scope, precedence is **local → project → user**. The winning entry is used whole; fields are not merged. > [!WARNING] > > Avoid `--scope project` for Prowler. That writes `.mcp.json` into your repository, and committing the file would publish your API key. > [!NOTE] > > **Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. ## Verify the Connection ```bash theme={null} claude mcp get prowler # shows which scope holds the definition claude mcp list # lists all servers and their status ``` Inside a Claude Code session, run `/mcp` to see connected servers and their tools. ![Claude Code session showing the /mcp command output with the Prowler server connected](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/claude/claude-code-mcp-command.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=ac51219b883679739ecd3d6d201d164d) ## Start Using Prowler MCP * *"Show me all critical findings from my AWS accounts"* * *"What does the S3 bucket public access check do?"* * *"Onboard this new AWS account in my Prowler organization"* ![Claude Code answering a question about critical findings using Prowler MCP tools](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/claude/claude-code-prowler-query.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=515552d82c8d6e31f52230ef8609c9ce) *** # Claude Code in the Desktop App (Code Tab) The **Code** tab in the Claude desktop app runs the same Claude Code as the CLI, and reads the same `~/.claude.json`. There is no separate Prowler setup for it — you configure it **from a terminal** and the Code tab picks it up. > [!NOTE] > > **Use [Option 2](#option-2-connect-the-mcp-server-only) with `--scope user` here.** It is the recommended setup for the Code tab. The Prowler plugin ([Option 1](#option-1-install-the-prowler-plugin)) is not the recommended route for the desktop app — install it in the Claude Code CLI instead. > [!WARNING] > > **You cannot do this from inside the app.** The desktop app has no interface for adding an MCP server to a Claude Code session. **Settings → Connectors** configures the **Chat** tab, not the **Code** tab, so anything added there never reaches Claude Code. Trying to configure it from the app is the main reason this appears not to work. **1. Add the server at user scope from a terminal** In a normal terminal — not inside the app: ```bash theme={null} export PROWLER_API_KEY="pk_your_api_key_here" claude mcp add --transport http prowler https://mcp.prowler.com/mcp \ --header "Authorization: Bearer $PROWLER_API_KEY" \ --scope user ``` `--scope user` is what makes this work. It writes to `~/.claude.json`, the file the Code tab reads. **2. Confirm it landed at user scope** ```bash theme={null} claude mcp get prowler ``` The scope must be `user`. A `local`-scoped server is bound to the directory you ran the command in and will not load in an app session opened elsewhere. **3. Restart the Claude app** Quit the app completely and reopen it. Configuration is read at startup. **4. Verify in the Code tab** Open a **Code** tab session and ask for a Prowler tool: "Do you have access to the Prowler MCP tools?", it should respond with a list of available tools or confirming that it has access. *** # Claude App Chat (Chat Tab) Not covered by this page. The **Chat** tab is a separate surface: it does not read `~/.claude.json`, so a server added with `claude mcp add` appears in the CLI and in the Code tab but **never** in Chat. That is expected behavior, not a broken setup. Chat reads `claude_desktop_config.json` and reaches the Prowler MCP Server through a local bridge. > [card] [Connect the Claude App Chat](/user-guide/ai-agents/claude-desktop) > > Separate guide: local bridge and its own configuration file *** # Troubleshooting | Symptom | Likely cause | Fix | | - | - | - | | `/mcp` shows `prowler` as failed | Rejected API key | Generate a new one in Prowler Cloud. With the plugin, reinstall it to re-prompt. | | No MCP servers configured | Server added at `local` scope from another directory | Run `claude mcp get prowler`, then re-add with `--scope user`. | | A stale entry overrides a working one | Precedence is local → project → user | `claude mcp remove prowler --scope local` | | Tools appear in the CLI but not in the app's **Code** tab | Server added at `local` scope, or the app was not restarted | Re-add with `--scope user`, then quit and reopen the app. See [Claude Code in the Desktop App](#claude-code-in-the-desktop-app-code-tab). | | Tools appear in the **Code** tab but not the **Chat** tab | Chat is a different surface with its own config file | Expected. Set Chat up separately, see [Claude App Chat](/user-guide/ai-agents/claude-desktop). | | No way to add the server from inside the app | The app has no MCP interface for Claude Code sessions | Configure it from a terminal with `--scope user`, then restart the app. See [Claude Code in the Desktop App](#claude-code-in-the-desktop-app-code-tab). | | Skill not invoked when expected | The prompt didn't match any skill's description | Name the task explicitly. For compliance triage, mention the framework plus "compliance" or "compliant". | | "Framework not supported" | Prowler Hub does not list the framework for that provider | Open an issue or PR at [github.com/prowler-cloud/prowler](https://github.com/prowler-cloud/prowler). | ### Authentication Fails With 401 * Confirm the header value includes the `Bearer ` prefix. * Check that `PROWLER_API_KEY` was set when you ran `claude mcp add` — the shell expands it at that moment and stores the resulting literal value. If the variable was empty, the stored header reads `Bearer ` with nothing after it. Verify with `claude mcp get prowler`. * Confirm the key has not been revoked in Prowler Cloud. ## Next Steps > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools and capabilities > [card] [All MCP Clients](/getting-started/basic-usage/prowler-mcp) > > Configuration reference for every supported client ## Getting Help * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Connect the Claude App Chat to Prowler MCP Server Source: https://docs.prowler.com/user-guide/ai-agents/claude-desktop Connect the **Chat** tab of the Claude desktop app to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp`. > [!WARNING] > > **This page covers the Chat tab only.** Looking for **Claude Code** — either the CLI or the app's **Code** tab? Those are a different surface, with a different configuration file and a different connection method. See [Connect Claude Code](/user-guide/ai-agents/claude-code). ## Prerequisites * **Claude desktop app** installed and signed in. * **Node.js and npm**, to install the bridge. * **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). ## Why "Add Custom Connector" Does Not Work The app's **Settings → Connectors → Add custom connector** dialog is the obvious place to paste an MCP URL, but it does not fit the Prowler Cloud MCP Server for two independent reasons: 1. **Connectors authenticate with OAuth.** Authenticating with a fixed API key sent as a request header is a separate mechanism that Anthropic documents as **beta**, rolled out on request. Without it, the dialog offers a URL and OAuth client credentials, with nowhere to supply `Authorization: Bearer pk_...`. 2. **Connectors do not connect from your machine.** Claude reaches your MCP server from Anthropic's cloud infrastructure rather than your local device. A Prowler MCP Server on `localhost`, behind a VPN, or restricted by an IP allowlist is unreachable that way regardless of authentication. Use a local bridge instead, as described below. ## Step 1: Get Your Prowler API Key Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. ## Step 2: Install the Bridge `mcp-remote` presents the remote HTTP server to Claude as a local STDIO server and injects the `Authorization` header. Install a pinned version into a dedicated directory: ```bash theme={null} mkdir -p ~/.local/share/prowler-mcp-bridge cd ~/.local/share/prowler-mcp-bridge npm init -y npm install --save-exact mcp-remote@0.1.38 ``` > [!WARNING] > > Do not configure Claude to run `npx mcp-remote` directly. `npx` can fetch and execute a new version on every launch, which means unreviewed code runs with access to your API key. Install a pinned version and point Claude at the installed binary. > [!NOTE] > > `mcp-remote` is community-maintained and is not an Anthropic product. Review it before use. ## Step 3: Edit the Configuration File In the Claude app, go to **Settings → Developer** and click **Edit Config**. This reveals `claude_desktop_config.json`: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ![Claude app Settings Developer tab showing the Edit Config button](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/claude/claude-desktop-developer-settings.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=da40d066107b652e48a8621d78024545) Add the following, replacing the `command` path with the absolute path to the installed binary and the placeholder with your API key: ```json theme={null} { "mcpServers": { "prowler": { "command": "/absolute/path/to/.local/share/prowler-mcp-bridge/node_modules/.bin/mcp-remote", "args": [ "https://mcp.prowler.com/mcp", "--header", "Authorization: Bearer ${PROWLER_API_KEY}" ], "env": { "PROWLER_API_KEY": "pk_your_api_key_here" } } } } ``` > [!NOTE] > > **Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. ## Step 4: Restart the App Quit the Claude app completely and reopen it. Configuration is read at startup. ## Step 5: Start Using Prowler MCP Open a Chat conversation and ask questions that use the Prowler tools: * *"Show me all critical findings from my AWS accounts"* * *"What does the S3 bucket public access check do?"* * *"Summarize my CIS compliance status by provider"* ![Claude app chat showing the Prowler MCP tools available](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/claude/claude-desktop-prowler-tools.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=6f9ac2d69c1c01d5454036b8c8f00db6) ## Troubleshooting ### Server Does Not Appear After Editing the Config * Quit and reopen the app entirely — closing the window is not enough on macOS. * Confirm `claude_desktop_config.json` is valid JSON. * Confirm the `command` path points at a real executable. A wrong path surfaces as the server failing to start rather than as an auth error. ### Tools Appear in Claude Code but Not in Chat Expected. The Chat tab does not read `~/.claude.json`, so servers added with `claude mcp add` never appear here. The Chat tab needs an entry in `claude_desktop_config.json`, which is what this guide sets up. ### Authentication Fails With 401 * Confirm the header value includes the `Bearer ` prefix. * Confirm the key has not been revoked in Prowler Cloud. ### Checking the Logs * **macOS:** `~/Library/Logs/Claude/mcp*.log` * **Windows:** `%APPDATA%\Claude\logs\mcp*.log` ```bash theme={null} tail -f ~/Library/Logs/Claude/mcp*.log ``` ## Next Steps > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools and capabilities > [card] [All MCP Clients](/getting-started/basic-usage/prowler-mcp) > > Configuration reference for every supported client ## Getting Help * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Connect Codex / ChatGPT Desktop to Prowler MCP Server Source: https://docs.prowler.com/user-guide/ai-agents/codex Connect [OpenAI Codex](https://learn.chatgpt.com/docs/extend/mcp) to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so Codex can query findings, inspect checks, and manage your Prowler providers. ## Which Codex Surfaces Work Codex keeps MCP servers in one file, `~/.codex/config.toml`. You can set it up from either the **Codex / ChatGPT desktop app** or the **Codex CLI** — both write to that same file, so pick whichever you already use. | Surface | Set it up here | Notes | | - | - | - | | **[Codex / ChatGPT desktop app](https://learn.chatgpt.com/docs/app)** (macOS, Windows) | ✅ Yes | **Settings → MCP servers** | | **Codex CLI** (terminal) | ✅ Yes | `codex mcp` commands | | **Codex IDE extension** (VS Code) | Inherits | Works automatically once the app or CLI is configured | | **ChatGPT on the web** | ❌ No | Does not read local Codex configuration | > [!NOTE] > > **Codex and ChatGPT share one desktop app.** Since July 2026 the standalone Codex app and the ChatGPT desktop app are the same application: Codex is a dedicated coding surface inside it, alongside Chat and Work. If you already had the Codex app, updating turns it into the new ChatGPT desktop app and it still opens in Codex. Either way, this guide applies. > > Not to be confused with **ChatGPT Classic**, the name given to the previous-generation ChatGPT desktop app. > [!NOTE] > > **Configure once, use everywhere.** The Codex documentation states that the ChatGPT desktop app, Codex CLI, and IDE extension "share this configuration. Once you configure your MCP servers, you can switch among those clients without redoing setup." Set the server up in the app or the CLI and the IDE extension picks it up with no extra work. ## Prerequisites * **The Codex / ChatGPT desktop app, or Codex CLI 0.46.0 or later.** Remote MCP servers over streamable HTTP were added to the CLI in 0.46.0 — check with `codex --version` and upgrade if needed. * **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). ## Step 1: Get Your Prowler API Key Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. ## Step 2: Add the Prowler MCP Server The Prowler MCP Server needs two request headers: `Authorization` to authenticate you, and `User-Agent` because Codex does not send one by default. Each tab below is a complete setup — follow the one that matches the surface you use. > [tab] Codex / ChatGPT desktop app > > 1. Open **Settings** and select **Plugins → MCPs** > > 2. Click **Add server** > > 3. Enter `prowler` as the name and choose type **Streamable HTTP** > > 4. Enter the URL `https://mcp.prowler.com/mcp` > > 5. Add two headers: > > | Header | Value | > | - | - | > | `Authorization` | `Bearer pk_your_api_key_here` | > | `User-Agent` | `codex` | > > 6. Save the server > > ![Codex / ChatGPT desktop app Settings showing the MCP servers panel with the Add server dialog and both headers filled in](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/codex/codex-app-mcp-servers.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=dcf3c028252e9a505843821024cb1a86) > > > [!NOTE] > > > > **Enter the key directly here rather than using an environment variable.** Codex can read credentials from an environment variable, but desktop applications do not reliably inherit variables exported in a shell profile — on macOS an app launched from Finder or the Dock typically sees none of them. Pasting the key into the dialog is the approach that works consistently in the app. > > > [!WARNING] > > > > **This stores your API key in plain text** in `~/.codex/config.toml`. Treat that file accordingly: exclude it from dotfile repositories and config sync, and create the key from an account with the minimum permissions you need so its exposure is limited. Revoke and re-issue the key in Prowler Cloud if the file is ever shared. > [tab] Codex CLI > > Register the server: > > ```bash theme={null} > codex mcp add prowler --url https://mcp.prowler.com/mcp > ``` > > Codex confirms with `Added global MCP server 'prowler'.` > > Then add both headers by hand, since `codex mcp add` has no flag for headers. Open `~/.codex/config.toml` and complete the entry: > > ```toml theme={null} > [mcp_servers.prowler] > url = "https://mcp.prowler.com/mcp" > http_headers = { Authorization = "Bearer pk_your_api_key_here", "User-Agent" = "codex" } > ``` > > > [!NOTE] > > > > **Write the key literally rather than using an environment variable.** This is the form that works across every Codex surface. All of them read this same file, but only the CLI reliably sees variables exported in your shell profile — see the warning below. > > > [!WARNING] > > > > **This stores your API key in plain text** in `~/.codex/config.toml`. Treat that file accordingly: exclude it from dotfile repositories and config sync, and create the key from an account with the minimum permissions you need so its exposure is limited. Revoke and re-issue the key in Prowler Cloud if the file is ever shared. Restart Codex once you are done. > [!NOTE] > > **Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. ## Step 3: Verify the Connection Run `/mcp` in the app or in a CLI session to list connected servers and their tools. ![Codex composer showing the /mcp command output with Prowler tools listed](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/codex/codex-mcp-slash-command.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=99986572a6ec1958de1128c0605aa03b) From the CLI you can also inspect the stored entry directly: ```bash theme={null} codex mcp list # one row per server, with status and auth codex mcp get prowler # full entry, header values masked ``` > [!WARNING] > > **Verify rather than assume.** Codex silently ignores unrecognized keys in `config.toml` — a misspelled key name produces no error at all, and the server simply never receives your credentials. Always confirm with `codex mcp get prowler` after editing the file by hand. ## Step 4: Start Using Prowler MCP Ask Codex questions that use the Prowler tools: * *"Show me all critical findings from my AWS accounts"* * *"What does the S3 bucket public access check do?"* * *"List my connected Prowler providers and their last scan date"* ![Codex answering a question about critical findings using Prowler MCP tools](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/codex/codex-prowler-query.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=90bf49dab954f1f15dd5ac88085e8148) ## Troubleshooting ### Startup Fails With HTTP 403 Forbidden Codex reports a handshake failure on startup, with an HTML error page rather than a JSON response: ``` ⚠ MCP client for `prowler` failed to start: MCP startup failed: handshaking with MCP server failed: ... unexpected server response: HTTP 403: 403 Forbidden ``` The `User-Agent` header is missing. Codex's HTTP client does not send one, and requests without it are rejected before reaching the MCP server. Note this is a **403**, not a 401 — so it is not an API key problem. Add the header as shown in [Step 2](#step-2-add-the-prowler-mcp-server); the value itself does not matter, only that the header is present. ### Authentication Fails With 401 * Run `codex mcp get prowler` and confirm the entry has the headers you expect. Values are masked, but a missing header shows as `-`. * If you used a literal header, confirm the value starts with `Bearer ` and contains the full key. * **If it works in the CLI but fails in the desktop app or the VS Code extension, you are almost certainly using an environment variable.** Those surfaces do not inherit your shell profile. Switch that entry to a literal `Authorization` header as shown in [Step 2](#step-2-add-the-prowler-mcp-server). * If you use an environment variable, verify it is set in the environment Codex was launched from: `echo $PROWLER_API_KEY`. * With `env_http_headers` the variable must include the `Bearer ` prefix. With `bearer_token_env_var` it must **not** — Codex adds the prefix itself. * Confirm the key has not been revoked in Prowler Cloud. ### Server Not Listed * Confirm your Codex CLI version is 0.46.0 or later with `codex --version`. * Run `codex mcp get prowler`. If it reports the server is not found, the entry was not written or the TOML table name is misspelled. * Check for a typo in the key names. Codex ignores unknown keys without warning. ### Project-Scoped Config Is Ignored A `.codex/config.toml` inside a project is loaded **only when the project is trusted**. If your entry lives there and does nothing, trust the project or move the entry to `~/.codex/config.toml`. ### Tools Do Not Appear After Editing the Config Restart Codex. Configuration is read at startup. In the app, quit completely and reopen it, sometimes just closing the window is not enough. ## Next Steps > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools and capabilities > [card] [All MCP Clients](/getting-started/basic-usage/prowler-mcp) > > Configuration reference for every supported client ## Getting Help * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Connect Cursor to Prowler MCP Server Source: https://docs.prowler.com/user-guide/ai-agents/cursor Connect [Cursor](https://cursor.com/docs/mcp) to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so the Cursor agent can query findings, inspect security checks, and manage your Prowler providers while you work. Cursor supports remote MCP servers over HTTP natively, so no bridge or local installation is required. ## Prerequisites * **Cursor** installed and authenticated. See the [official install guide](https://cursor.com/download). * **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). ## Step 1: Get Your Prowler API Key Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. ## Step 2: Add the Prowler MCP Server Cursor reads MCP servers from an `mcp.json` file. Choose the scope that fits your use case: | Scope | File | Applies to | | - | - | - | | **Global** | `~/.cursor/mcp.json` | Every project you open in Cursor | | **Project** | `.cursor/mcp.json` in the project root | That project only | Both files are merged. If the same server name appears in both, the project-level entry takes priority. For Prowler, the **global** scope is usually the right choice — your findings are not tied to a single repository, and it keeps the API key out of any project directory that might be committed. **1. Open the MCP settings** From Agent Window open **Customize** in the Cursor sidebar, then select the MCP section. On earlier versions, press `Cmd + Shift + J` (macOS) or `Ctrl + Shift + J` (Windows/Linux) to open Cursor Settings, then click **Tools & MCP** in the sidebar. **2. Add a new MCP server** Click **New MCP Server** (or **Add Custom MCP**). Cursor opens `mcp.json` in the editor. ![Cursor Customize page with the MCP section open](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/cursor/cursor-customize-page.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=73bd143ac9e5380a327abcdcb5b54196) **3. Add the Prowler configuration** Paste the following, replacing the placeholder with your API key: ```json theme={null} { "mcpServers": { "prowler": { "url": "https://mcp.prowler.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Save the file. Cursor picks up the change and connects to the server. ![Cursor editor showing the completed mcp.json with the Prowler server entry](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/cursor/cursor-mcp-json.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=f7ad602b22e46dd4c782d969511029e9) > [!NOTE] > > **Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. ### Keeping the API Key Out of the File Cursor resolves variables in the `command`, `args`, `env`, `url`, and `headers` fields, so you can reference an environment variable instead of writing the key into `mcp.json`: ```json theme={null} { "mcpServers": { "prowler": { "url": "https://mcp.prowler.com/mcp", "headers": { "Authorization": "Bearer ${env:PROWLER_API_KEY}" } } } } ``` Export the variable in your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent): ```bash theme={null} export PROWLER_API_KEY="pk_your_api_key_here" ``` > [!NOTE] > > The syntax is `${env:NAME}`, not a bare `${NAME}`. Restart Cursor after changing your shell profile so it inherits the new value. > [!WARNING] > > The `envFile` option does **not** work for remote servers — it is STDIO-only. Use `${env:...}` interpolation with variables set in your shell profile instead. This form is strongly recommended when using a **project-scoped** `.cursor/mcp.json`, since that file may be committed to version control. ## Step 3: Verify the Connection Return to the MCP settings. The `prowler` server should be listed as enabled, with the Prowler tools shown beneath it. ![Cursor MCP settings showing the Prowler server connected with its tools listed](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/cursor/cursor-prowler-connected.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=0124288337b47570b2af0cdd43c257bc) ## Step 4: Start Using Prowler MCP Open the chat panel and ask questions that use the Prowler tools: * *"Show me all critical findings from my AWS accounts"* * *"What does the S3 bucket public access check do?"* * *"Which of my providers failed the most CIS checks in the last scan?"* Cursor asks for approval before running an MCP tool the first time. ![Cursor chat answering a question about critical findings using Prowler MCP tools](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/cursor/cursor-prowler-query.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=bf0bf0da9ad9d7551d28c557f466b5fe) You can toggle individual tools on or off from the tools list at the top of the chat panel, which is useful for keeping the active tool count down. ## Troubleshooting ### Server Does Not Connect * Check that `mcp.json` is valid JSON. A trailing comma or missing brace prevents the whole file from loading. * Open **MCP Logs** in the Output panel for the specific error. * Confirm the URL is exactly `https://mcp.prowler.com/mcp`. ### Authentication Fails With 401 * Verify the header value includes the `Bearer ` prefix: `"Bearer pk_..."`, not just the key. * Confirm the key has not been revoked in Prowler Cloud. * If using `${env:PROWLER_API_KEY}`, check the variable is set in the environment Cursor inherits. Restart Cursor after editing your shell profile — a value exported only in an already-open terminal will not reach the app. ### The Entire `mcp.json` Is Ignored Remove any `"type": "streamable-http"` field. One such entry causes the Cursor CLI to drop every server in the file silently. ### Some Prowler Tools Are Missing Cursor limits how many tools it exposes to the agent at once. With several MCP servers enabled you may exceed it, and some tools become unavailable. Disable servers you are not using, or turn off individual tools from the chat panel's tools list. ## Next Steps > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools and capabilities > [card] [All MCP Clients](/getting-started/basic-usage/prowler-mcp) > > Configuration reference for every supported client ## Getting Help * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Connect Your AI Agent to Prowler Source: https://docs.prowler.com/user-guide/ai-agents/index Pick your AI agent and follow its guide to connect it to the Prowler Cloud MCP Server. Connect your AI agent to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so it can query findings, inspect security checks, and manage your Prowler providers. Pick your agent below. Each guide is a full walkthrough with screenshots, verification steps, and the caveats specific to that client. > [card] [Claude Code](/user-guide/ai-agents/claude-code) > > Plugin and MCP-only choices, and which Claude surfaces work > [card] [Claude Desktop App (Chat)](/user-guide/ai-agents/claude-desktop) > > The Chat tab, via a local bridge > [card] [Codex / ChatGPT Desktop App](/user-guide/ai-agents/codex) > > ChatGPT Desktop App, Codex CLI, the VS Code extension through same config file > [card] [Cursor](/user-guide/ai-agents/cursor) > > Agentic code editor. Global and project scopes > [card] [VS Code / Copilot](/user-guide/ai-agents/vscode) > > Agent mode with secure key prompts ## Before You Start All guides need the same two things: * A **Prowler Cloud account** with at least one cloud provider connected. [Sign up](https://cloud.prowler.com) if you do not have one. * A **Prowler API key**, created in Prowler Cloud. The key begins with `pk_` and is shown only once. See the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide. > [!NOTE] > > Using an agent that is not listed here? Any MCP-compatible client can connect. See the [generic configuration reference](/getting-started/basic-usage/prowler-mcp#cloud-mcp-server-configuration-recommended) for the raw connection details. ## Next Steps > [card] [What Is Prowler MCP](/getting-started/products/prowler-mcp) > > How the MCP Server fits into Prowler > [card] [Configuration Reference](/getting-started/basic-usage/prowler-mcp) > > Cloud and local server options, all clients # Connect VS Code and GitHub Copilot to Prowler MCP Server Source: https://docs.prowler.com/user-guide/ai-agents/vscode Connect [Visual Studio Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) and GitHub Copilot agent mode to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so Copilot can query findings, inspect security checks, and manage your Prowler providers. ## Prerequisites * **VS Code 1.102 or later.** MCP support became generally available in 1.102. * **GitHub Copilot** enabled, with access to agent mode. * **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). ## Step 1: Get Your Prowler API Key Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. ## Step 2: Add the Prowler MCP Server VS Code stores MCP servers in an `mcp.json` file. Choose the scope that fits your use case: | Scope | How to open it | Applies to | | - | - | - | | **User** | Command palette → **MCP: Open User Configuration** | Every workspace | | **Workspace** | `.vscode/mcp.json` in the project root | That workspace only | For Prowler, the **user** scope is usually the right choice — your findings are not tied to a single repository, and it keeps the API key out of any project directory that might be committed. **1. Open the MCP configuration** Open the command palette with `Cmd + Shift + P` (macOS) or `Ctrl + Shift + P` (Windows/Linux), then run **MCP: Open User Configuration**. VS Code opens your user-level `mcp.json`. Use this command rather than navigating to the file by hand — the file lives inside your active profile folder, and the path differs per profile. ![VS Code command palette showing the MCP: Open User Configuration command](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/vscode/vscode-command-palette.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=d0071776901c28024682e32ecf82cf30) **2. Add the Prowler configuration** Paste the following. This version prompts you for the API key on first use and stores it securely, so the key is never written into the file: ```json theme={null} { "inputs": [ { "type": "promptString", "id": "prowler-api-key", "description": "Prowler API Key", "password": true } ], "servers": { "prowler": { "type": "http", "url": "https://mcp.prowler.com/mcp", "headers": { "Authorization": "Bearer ${input:prowler-api-key}" } } } } ``` Save the file. ![VS Code editor showing the completed mcp.json with the Prowler server entry](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/vscode/vscode-mcp-json.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=31a17e5fb88fd0497171b01446b2d9e1) **3. Enter your API key** Start the server. VS Code prompts for the Prowler API key. Paste it and press Enter — VS Code stores it securely and does not ask again. > [!WARNING] > > **The root key is `servers`, not `mcpServers`.** VS Code uses a different schema from Cursor, Claude, and most other clients. Copying a `mcpServers` snippet from elsewhere silently fails to register the server. > [!NOTE] > > **Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. ## Step 3: Verify the Connection Run **MCP: List Servers** from the command palette. The `prowler` server should appear as running. ![VS Code MCP: List Servers output showing the Prowler server running](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/vscode/vscode-list-servers.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=84dead7ef412cadf00ff1e1ebc6be182) Select the server to start, stop, or restart it, and to view its output log if the connection fails. ## Step 4: Start Using Prowler MCP Open the Chat view and switch the mode selector to **Agent**. Click the tools icon to confirm the Prowler tools are available, then ask: * *"Show me all critical findings from my AWS accounts"* * *"What does the S3 bucket public access check do?"* * *"Summarize my CIS compliance status by provider"* ![VS Code Copilot Chat in agent mode showing the Prowler tools in the tools picker](https://mintcdn.com/prowler/KHRvqU0mtAjtmxha/images/prowler-mcp/vscode/vscode-agent-tools.png?fit=max\&auto=format\&n=KHRvqU0mtAjtmxha\&q=85\&s=86da09063d62edececb1a5a2fdf6f848) Copilot asks for confirmation before running an MCP tool for the first time. ## Troubleshooting ### Server Does Not Appear * Confirm the root key is `servers`, not `mcpServers`. * Confirm each server entry has `"type": "http"`. * Check that `mcp.json` is valid JSON. * Verify your VS Code version is 1.102 or later. ### Authentication Fails With 401 * Verify the header value includes the `Bearer ` prefix. * Confirm the key has not been revoked in Prowler Cloud. * If you mistyped the key at the prompt, run **MCP: List Servers**, select `prowler`, and restart it to be prompted again. ### Tools Do Not Appear in Chat * Make sure the Chat view is in **Agent** mode. MCP tools are not available in Ask mode. * Open the tools picker and confirm the Prowler tools are enabled. ## Next Steps > [card] [Tools Reference](/getting-started/basic-usage/prowler-mcp-tools) > > Explore all available tools and capabilities > [card] [All MCP Clients](/getting-started/basic-usage/prowler-mcp) > > Configuration reference for every supported client ## Getting Help * Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) * Ask for help in our [Slack community](https://goto.prowler.com/slack) * Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) # Check Aliases Source: https://docs.prowler.com/user-guide/cli/tutorials/check-aliases Prowler allows you to use aliases for the checks. You only have to add the `CheckAliases` key to the check's metadata with a list of the aliases: ```json title="check.metadata.json" theme={null} "Provider": "", "CheckID": "", "CheckTitle": "", "CheckAliases": [ "" "", ... ], ... ``` Then you can execute the check either with its check ID or with one of the previous aliases: ```shell theme={null} prowler -c/--checks Using alias for check ... ``` # Configuration File Source: https://docs.prowler.com/user-guide/cli/tutorials/configuration_file Several Prowler's checks have user configurable variables that can be modified in a common **configuration file**. This file can be found in the following [path](https://github.com/prowler-cloud/prowler/blob/master/prowler/config/config.yaml): ``` prowler/config/config.yaml ``` Additionally, you can input a custom configuration file using the `--config-file` argument. > [!NOTE] > > Numeric thresholds enforce hard limits. A value outside the accepted range is dropped with a warning and the check falls back to its built-in default. See [Configuration Value Limits](/developer-guide/configurable-checks#configuration-value-limits) for the exact range of every bounded option (max-days caps, percentages, counts, etc.). ## AWS ### Configurable Checks The following list includes all the AWS checks with configurable variables that can be changed in the configuration yaml file: | Check Name | Value | Type | Default | | - | - | - | - | | `accessanalyzer_enabled` | `mute_non_default_regions` | Boolean | `False` | | `acm_certificates_expiration_check` | `days_to_expire_threshold` | Integer | `7` | | `acm_certificates_with_secure_key_algorithms` | `insecure_key_algorithms` | List of Strings | `["RSA-1024", "P-192"]` | | `acmpca_certificate_authority_pqc_key_algorithm` | `acmpca_pqc_key_algorithms` | List of Strings | `["ML_DSA_44", "ML_DSA_65", "ML_DSA_87"]` | | `apigateway_domain_name_pqc_tls_enabled` | `apigateway_pqc_tls_allowed_policies` | List of Strings | `["SecurityPolicy_TLS13_1_2_FIPS_PFS_PQ_2025_09", "SecurityPolicy_TLS13_1_2_PFS_PQ_2025_09", "SecurityPolicy_TLS13_1_2_PQ_2025_09"]` | | `apigateway_restapi_no_secrets_in_stage_variables` | `secrets_ignore_patterns` | List of Strings | `[]` | | `appstream_fleet_maximum_session_duration` | `max_session_duration_seconds` | Integer | `36000` | | `appstream_fleet_session_disconnect_timeout` | `max_disconnect_timeout_in_seconds` | Integer | `300` | | `appstream_fleet_session_idle_disconnect_timeout` | `max_idle_disconnect_timeout_in_seconds` | Integer | `600` | | `autoscaling_find_secrets_ec2_launch_configuration` | `secrets_ignore_patterns` | List of Strings | `[]` | | `awslambda_function_no_secrets_in_code` | `secrets_ignore_files` | List of Strings | `[]` | | `awslambda_function_no_secrets_in_code` | `secrets_ignore_patterns` | List of Strings | `[]` | | `awslambda_function_no_secrets_in_variables` | `secrets_ignore_patterns` | List of Strings | `[]` | | `awslambda_function_using_supported_runtimes` | `obsolete_lambda_runtimes` | List of Strings | See `config.yaml` | | `awslambda_function_vpc_multi_az` | `lambda_min_azs` | Integer | `2` | | `elasticbeanstalk_environment_php_platform_updated` | `elasticbeanstalk_php_min_branch` | String | `"8.2"` | | `elasticbeanstalk_environment_php_platform_updated` | `elasticbeanstalk_php_min_platform_version` | String | `"4.13.13"` | | `lightsail_instance_php_blueprint_updated` | `lightsail_php_blueprints` | List of Strings | See `config.yaml` | | `cloudformation_stack_cdktoolkit_bootstrap_version` | `recommended_cdk_bootstrap_version` | Integer | `21` | | `cloudformation_stack_outputs_find_secrets` | `secrets_ignore_patterns` | List of Strings | `[]` | | `cloudfront_distributions_pqc_tls_enabled` | `cloudfront_pqc_min_protocol_versions` | List of Strings | `["TLSv1.3_2025"]` | | `cloudtrail_threat_detection_enumeration` | `threat_detection_enumeration_actions` | List of Strings | See `config.yaml` | | `cloudtrail_threat_detection_enumeration` | `threat_detection_enumeration_minutes` | Integer | `1440` | | `cloudtrail_threat_detection_enumeration` | `threat_detection_enumeration_threshold` | Float | `0.3` | | `cloudtrail_threat_detection_llm_jacking` | `threat_detection_llm_jacking_actions` | List of Strings | See `config.yaml` | | `cloudtrail_threat_detection_llm_jacking` | `threat_detection_llm_jacking_minutes` | Integer | `1440` | | `cloudtrail_threat_detection_llm_jacking` | `threat_detection_llm_jacking_threshold` | Float | `0.4` | | `cloudtrail_threat_detection_privilege_escalation` | `threat_detection_privilege_escalation_actions` | List of Strings | See `config.yaml` | | `cloudtrail_threat_detection_privilege_escalation` | `threat_detection_privilege_escalation_minutes` | Integer | `1440` | | `cloudtrail_threat_detection_privilege_escalation` | `threat_detection_privilege_escalation_threshold` | Float | `0.2` | | `cloudwatch_log_group_agentcore_data_protection_policy_enabled` | `agentcore_log_group_name_prefixes` | List of Strings | See `config.yaml` | | `cloudwatch_log_group_no_secrets_in_logs` | `secrets_ignore_patterns` | List of Strings | `[]` | | `cloudwatch_log_group_retention_policy_specific_days_enabled` | `log_group_retention_days` | Integer | `365` | | `codebuild_project_no_secrets_in_variables` | `excluded_sensitive_environment_variables` | List of Strings | `[]` | | `codebuild_project_no_secrets_in_variables` | `secrets_ignore_patterns` | List of Strings | `[]` | | `codebuild_project_uses_allowed_github_organizations` | `codebuild_github_allowed_organizations` | List of Strings | `[]` | | `config_delegated_admin_and_org_aggregator_all_regions` | `mute_non_default_regions` | Boolean | `False` | | `config_recorder_all_regions_enabled` | `mute_non_default_regions` | Boolean | `False` | | `documentdb_cluster_backup_enabled` | `minimum_backup_retention_period` | Integer | `7` | | `drs_job_exist` | `mute_non_default_regions` | Boolean | `False` | | `dynamodb_table_cross_account_access` | `trusted_account_ids` | List of Strings | `[]` | | `ec2_elastic_ip_shodan` | `shodan_api_key` | String | `null` | | `ec2_instance_older_than_specific_days` | `max_ec2_instance_age_in_days` | Integer | `180` | | `ec2_instance_stopped_older_than_specific_days` | `max_ec2_instance_stopped_days` | Integer | `30` | | `ec2_instance_secrets_user_data` | `secrets_ignore_patterns` | List of Strings | `[]` | | `ec2_launch_template_no_secrets` | `secrets_ignore_patterns` | List of Strings | `[]` | | `ec2_securitygroup_allow_ingress_from_internet_to_any_port` | `ec2_allowed_instance_owners` | List of Strings | `["amazon-elb"]` | | `ec2_securitygroup_allow_ingress_from_internet_to_any_port` | `ec2_allowed_interface_types` | List of Strings | `["api_gateway_managed", "vpc_endpoint"]` | | `ec2_securitygroup_allow_ingress_from_internet_to_high_risk_tcp_ports` | `ec2_high_risk_ports` | List of Integer | `[25, 110, 135, 143, 445, 3000, 4333, 5000, 5500, 8080, 8088]` | | `ec2_securitygroup_with_many_ingress_egress_rules` | `max_security_group_rules` | Integer | `50` | | `ecr_repositories_scan_vulnerabilities_in_latest_image` | `ecr_repository_vulnerability_minimum_severity` | String | `"MEDIUM"` | | `ecs_service_fargate_latest_platform_version` | `fargate_linux_latest_version` | String | `"1.4.0"` | | `ecs_service_fargate_latest_platform_version` | `fargate_windows_latest_version` | String | `"1.0.0"` | | `ecs_task_definitions_no_environment_secrets` | `secrets_ignore_patterns` | List of Strings | `[]` | | `eks_cluster_uses_a_supported_version` | `eks_cluster_oldest_version_supported` | String | `"1.28"` | | `eks_control_plane_logging_all_types_enabled` | `eks_required_log_types` | List of Strings | `["api", "audit", "authenticator", "controllerManager", "scheduler"]` | | `elasticache_redis_cluster_backup_enabled` | `minimum_snapshot_retention_period` | Integer | `7` | | `elb_is_in_multiple_az` | `elb_min_azs` | Integer | `2` | | `elbv2_is_in_multiple_az` | `elbv2_min_azs` | Integer | `2` | | `elbv2_listener_pqc_tls_enabled` | `elbv2_listener_pqc_tls_allowed_policies` | List of Strings | See `config.yaml` | | `eventbridge_bus_cross_account_access` | `trusted_account_ids` | List of Strings | `[]` | | `eventbridge_schema_registry_cross_account_access` | `trusted_account_ids` | List of Strings | `[]` | | `glue_etl_jobs_no_secrets_in_arguments` | `secrets_ignore_patterns` | List of Strings | `[]` | | `guardduty_delegated_admin_enabled_all_regions` | `mute_non_default_regions` | Boolean | `False` | | `guardduty_is_enabled` | `mute_non_default_regions` | Boolean | `False` | | `iam_role_access_not_stale_to_bedrock` | `max_unused_bedrock_access_days` | Integer | `60` | | `iam_user_access_not_stale_to_bedrock` | `max_unused_bedrock_access_days` | Integer | `60` | | `iam_user_access_not_stale_to_sagemaker` | `max_unused_sagemaker_access_days` | Integer | `90` | | `iam_user_accesskey_unused` | `max_unused_access_keys_days` | Integer | `45` | | `iam_user_console_access_unused` | `max_console_access_days` | Integer | `45` | | `inspector2_active_findings_within_max_age` | `inspector2_active_finding_max_age_days` | Integer | `192` | | `inspector2_coverage_recently_scanned` | `inspector2_max_days_since_last_scan` | Integer | `3` | | `kinesis_stream_data_retention_period` | `min_kinesis_stream_retention_hours` | Integer | `168` | | `neptune_cluster_backup_enabled` | `minimum_backup_retention_period` | Integer | `7` | | `opensearch_service_domains_not_publicly_accessible` | `trusted_ips` | List of Strings | `[]` | | `organizations_delegated_administrators` | `organizations_trusted_delegated_administrators` | List of Strings | `[]` | | `organizations_scp_check_deny_regions` | `organizations_enabled_regions` | List of Strings | `[]` | | `rds_instance_backup_enabled` | `check_rds_instance_replicas` | Boolean | `False` | | `rolesanywhere_trust_anchor_pqc_pki` | `rolesanywhere_pqc_pca_key_algorithms` | List of Strings | `["ML_DSA_44", "ML_DSA_65", "ML_DSA_87"]` | | `s3_bucket_cross_account_access` | `trusted_account_ids` | List of Strings | `[]` | | `s3_bucket_object_public` | `s3_bucket_object_public_enabled` | Boolean | `False` | | `s3_bucket_object_public` | `s3_bucket_object_public_max_objects` | Integer | `100` | | `s3_bucket_object_public` | `s3_bucket_object_public_sample_size` | Integer | `3` | | `secretsmanager_has_restrictive_resource_policy` | `organizations_trusted_ids` | List of Strings | `[]` | | `secretsmanager_secret_rotated_periodically` | `max_days_secret_unrotated` | Integer | `90` | | `secretsmanager_secret_unused` | `max_days_secret_unused` | Integer | `90` | | `securityhub_delegated_admin_enabled_all_regions` | `mute_non_default_regions` | Boolean | `False` | | `securityhub_enabled` | `mute_non_default_regions` | Boolean | `False` | | `ssm_document_secrets` | `secrets_ignore_patterns` | List of Strings | `[]` | | `ssm_documents_set_as_public` | `trusted_account_ids` | List of Strings | `[]` | | `stepfunctions_statemachine_no_secrets_in_definition` | `secrets_ignore_patterns` | List of Strings | `[]` | | `transfer_server_pqc_ssh_kex_enabled` | `transfer_pqc_ssh_allowed_policies` | List of Strings | `["TransferSecurityPolicy-2025-03", "TransferSecurityPolicy-FIPS-2025-03", "TransferSecurityPolicy-AS2Restricted-2025-07"]` | | `trustedadvisor_premium_support_plan_subscribed` | `verify_premium_support_plans` | Boolean | `True` | | `vpc_endpoint_connections_trust_boundaries` | `trusted_account_ids` | List of Strings | `[]` | | `vpc_endpoint_services_allowed_principals_trust_boundaries` | `trusted_account_ids` | List of Strings | `[]` | ### Resource Scan Limit [Added in:  5.32.0](https://github.com/prowler-cloud/prowler/releases/tag/5.32.0) Some AWS services accumulate large numbers of resources (EBS snapshots, backup recovery points, CloudWatch log groups, Lambda functions, ECS task definitions, and CodeArtifact packages). Scanning every resource increases scan time, cost, API throttling, and finding volume. By default, Prowler scans every resource. Configure a positive resource scan limit to cap how many resources Prowler analyzes for these high-volume AWS resource paths. The global default applies to the supported resources below and is overridable per resource. The default global value is `0`, which disables the limit and scans every resource. A global `null` value is also unlimited. For per-resource values, `null` means inherit the global default; set `0` or a negative value to disable that resource limit explicitly. Positive values enable limits. > [!WARNING] > > When positive resource scan limits are configured, compliance results are based only on the selected resources, not on the full set of matching resources in the account. Treat compliance summaries and percentages as partial evidence, because unselected resources are not analyzed and can change the real compliance posture. #### Global Behavior Resource scan limits select resources for analysis. They do not cap, prioritize, or reorder findings. * **`0`, negative, or global `null` values:** Disable the limit and keep the legacy behavior for that resource path. Prowler analyzes every discovered matching resource. * **Positive values:** Select at most that many resources for the affected resource path. A selected resource can produce zero, one, or many findings. * **No PASS/FAIL prioritization:** Prowler does not inspect the compliance result before selecting resources. Limits do not prefer failed resources, passed resources, or resources with more findings. * **Latest-first where possible:** When AWS exposes timestamps or useful ordering, Prowler selects the newest resources first. When AWS only exposes API order, Prowler preserves that API order and documents the behavior as best effort. * **Findings are downstream:** Checks only evaluate the resources exposed by the service client after selection. Findings from unselected resources are not produced because those resources are not analyzed. Exact list API call reduction depends on each AWS API's ordering and pagination capabilities. When Prowler must enumerate candidates locally to select the latest resources, list calls may still read candidates, but expensive per-resource enrichment calls are bounded to the selected resources for the supported paths below. #### Full Collections Versus Limited Analysis Sets Some checks need lightweight evidence from a complete resource collection to avoid incorrect cross-service conclusions, while other checks perform primary analysis on a limited resource set. Prowler keeps full lightweight collections where they are needed for cross-service evidence. For example: * **Lambda security groups and regions:** Prowler records security groups used by all discovered Lambda functions and the regions where functions exist before it limits Lambda functions for primary Lambda checks. This helps Amazon EC2 and Amazon Inspector checks avoid false positives such as treating Lambda security groups as unused or assuming a region has no Lambda functions. * **CloudWatch `all_log_groups`:** Prowler records all discovered CloudWatch log groups in `all_log_groups` before limiting the primary `log_groups` analysis set. Other services can still resolve log group evidence, while CloudWatch log group checks only analyze the selected log groups. This split is intentional. It reduces expensive per-resource analysis calls without discarding lightweight context that other services need for accurate results. #### Supported AWS Resource Limits | Value | Scope | Type | | - | - | - | | `max_scanned_resources_per_service` | Global default for all supported high-volume AWS resources (default `0`, disabled/unlimited) | Integer | | `max_ebs_snapshots` | EBS snapshots (`ec2_ebs_*` checks) | Integer | | `max_backup_recovery_points` | Backup recovery points (`backup_recovery_point_*`) | Integer | | `max_cloudwatch_log_groups` | CloudWatch log groups (`cloudwatch_log_group_*`) | Integer | | `max_lambda_functions` | Lambda functions (`awslambda_function_*`) | Integer | | `max_ecs_task_definitions` | ECS task definitions (`ecs_task_definitions_*`) | Integer | | `max_codeartifact_packages` | CodeArtifact packages (`codeartifact_packages_*`) | Integer | #### Resource Limit Behavior By Resource Path | Resource Path | What Prowler Discovers | What A Positive Limit Selects For Analysis | Ordering And Latest Behavior | AWS Calls Reduced | Drawbacks And Consequences | | - | - | - | - | - | - | | EBS snapshots (`max_ebs_snapshots`) | Prowler lists self-owned snapshots and keeps lightweight evidence that volumes and regions have snapshots. | The selected EBS snapshots exposed to `ec2_ebs_*` checks. | Prowler sorts discovered snapshots by `StartTime` newest first, then applies the limit. Snapshots without a timestamp sort last. | Bounds expensive per-snapshot public attribute checks to selected snapshots. Snapshot listing still runs so Prowler can choose the newest snapshots and keep volume/region evidence. | Older unselected snapshots are not analyzed by snapshot checks. A public, unencrypted, or otherwise noncompliant older snapshot can be missed when the limit is lower than the number of snapshots. | | Backup recovery points (`max_backup_recovery_points`) | Prowler lists backup vaults, plans, selections, and recovery point candidates in discovered vaults. | The selected recovery points exposed to `backup_recovery_point_*` checks and tag hydration. | Prowler sorts discovered recovery points by `CreationDate` newest first across vaults, then applies the limit. Recovery points without a timestamp sort last. | Bounds recovery point tag calls to selected recovery points. Vault and recovery point list calls still run so Prowler can choose the newest points. | Older unselected recovery points are not analyzed. A nonencrypted or otherwise noncompliant older recovery point can be missed. | | CloudWatch log groups (`max_cloudwatch_log_groups`) | Prowler lists log groups into both `all_log_groups` and the primary `log_groups` collection. `all_log_groups` remains available as lightweight cross-service evidence. | The selected log groups exposed to `cloudwatch_log_group_*` checks, tag hydration, and log event retrieval for checks that need log contents. | Prowler sorts discovered log groups by `creationTime` newest first, then applies the limit. Log groups without a creation time sort last. | Bounds tag calls and log event retrieval to selected log groups. Log group listing still runs to build `all_log_groups` and choose newest log groups. | Older unselected log groups are not analyzed by CloudWatch log group checks. Retention, encryption, or secrets-in-logs issues in older log groups can be missed, although cross-service evidence can still use `all_log_groups`. | | Lambda functions (`max_lambda_functions`) | Prowler lists Lambda functions and records lightweight security group and region evidence for all discovered functions. | The selected Lambda functions exposed to `awslambda_function_*` checks and per-function enrichment such as tags, policies, function URLs, and event source mappings. | Prowler sorts discovered functions by `LastModified` newest first, then applies the limit. Functions without `LastModified` sort last. | Bounds per-function enrichment calls to selected functions. Function listing still runs to choose newest functions and keep security group/region evidence. | Older unselected functions are not analyzed by Lambda checks. Runtime, policy, URL, environment secret, or dead-letter queue issues in older functions can be missed. Cross-service checks can still use full Lambda security group and region evidence to avoid false positives. | | ECS task definitions (`max_ecs_task_definitions`) | Prowler lists ECS task definition ARN candidates in each region. Candidate ARNs can remain visible and discoverable through AWS list operations, even when not all are described. | The selected task definitions that Prowler describes and exposes to `ecs_task_definitions_*` checks. | Selection is not random. Prowler calls `ListTaskDefinitions` with `sort=DESC`, which asks AWS to return task definition ARNs in descending family and revision order. Prowler then interleaves regional candidate lists to avoid starving later regions before applying the limit. This selects the latest task definition revisions according to the ARN order AWS provides, while preserving regional fairness. | Bounds `DescribeTaskDefinition` calls to selected task definitions. Prowler may still list candidates so it can select the bounded set and keep discovery deterministic. | Unselected task definitions are not described or analyzed. Issues in older task definition revisions, or in lower-priority families outside the selected AWS `sort=DESC` order, can be missed. Because ECS ordering is family/revision based rather than a registration timestamp sort across every family, this is latest-first according to AWS task definition ARN ordering, not a global newest-by-time guarantee. | | CodeArtifact packages (`max_codeartifact_packages`) | Prowler lists CodeArtifact repositories and lazily lists packages inside them. | The selected packages exposed to `codeartifact_packages_*` checks, including latest-version metadata for those packages. | AWS `ListPackages` does not provide a newest-package timestamp ordering in this path. Prowler preserves repository order and package API order, then applies the limit. Latest package version metadata is retrieved for selected packages with `sortBy=PUBLISHED_TIME` and `maxResults=1`. | Bounds `ListPackageVersions` calls to selected packages and can stop package listing once the limit is reached. Repository listing still runs. | Package selection is best effort by API order, not newest package order. Packages outside the selected repository/API order are not analyzed, so origin restriction or latest-version issues can be missed. | Use limits when scan duration, API throttling, or cost are more important than exhaustive coverage for these high-volume resources. Keep limits disabled when you need complete evidence for every resource in the affected checks. ### Validating Discovered Secrets [Added in:  5.32.0](https://github.com/prowler-cloud/prowler/releases/tag/5.32.0) By default, the secret-scanning checks run fully offline: secrets are detected but never sent anywhere. Setting `secrets_validate` to `True` additionally confirms whether each discovered secret is live by authenticating with it against the corresponding provider API. The discovered secret itself serves as the credential, so Prowler requires no additional permissions to validate it. `secrets_validate` applies to every AWS secret-scanning check listed above (those that accept `secrets_ignore_patterns`). The `--scan-secrets-validate` CLI flag is provider-wide: it also enables validation for the secret-scanning checks of other providers, such as the OpenStack metadata checks. To enable validation through the configuration file, set the value under the `aws` section: ```yaml theme={null} aws: secrets_validate: True ``` To enable validation for a single scan (any provider), use Prowler CLI: ``` prowler aws --scan-secrets-validate ``` > [!WARNING] > > Secret validation makes outbound network calls that authenticate with each discovered secret. The credential is exercised against the provider, so the call appears in the audited account's logs and can trigger its monitoring (for example, AWS CloudTrail records the validation request). Validation stays disabled by default so that scans remain fully offline. ## Azure ### Configurable Checks The following list includes all the Azure checks with configurable variables that can be changed in the configuration yaml file: | Check Name | Value | Type | Default | | - | - | - | - | | `apim_threat_detection_llm_jacking` | `apim_threat_detection_llm_jacking_actions` | List of Strings | See `config.yaml` | | `apim_threat_detection_llm_jacking` | `apim_threat_detection_llm_jacking_minutes` | Integer | `1440` | | `apim_threat_detection_llm_jacking` | `apim_threat_detection_llm_jacking_threshold` | Float | `0.1` | | `app_ensure_java_version_is_latest` | `java_latest_version` | String | `"17"` | | `app_ensure_php_version_is_latest` | `php_latest_version` | String | `"8.5"` | | `app_ensure_python_version_is_latest` | `python_latest_version` | String | `"3.12"` | | `defender_attack_path_notifications_properly_configured` | `defender_attack_path_minimal_risk_level` | String | `"High"` | | `network_public_ip_shodan` | `shodan_api_key` | String | `null` | | `sqlserver_recommended_minimal_tls_version` | `recommended_minimal_tls_versions` | List of Strings | `["1.2", "1.3"]` | | `storage_smb_channel_encryption_with_secure_algorithm` | `recommended_smb_channel_encryption_algorithms` | List of Strings | `["AES-256-GCM"]` | | `vm_desired_sku_size` | `desired_vm_sku_sizes` | List of Strings | `["Standard_A8_v2", "Standard_DS3_v2", "Standard_D4s_v3"]` | | `vm_sufficient_daily_backup_retention_period` | `vm_backup_min_daily_retention_days` | Integer | `7` | ## GCP ### Configurable Checks The following list includes all the GCP checks with configurable variables that can be changed in the configuration yaml file: | Check Name | Value | Type | Default | | - | - | - | - | | `appengine_version_php_runtime_supported` | `appengine_php_min_version` | String | `"8.2"` | | `cloudstorage_bucket_sufficient_retention_period` | `storage_min_retention_days` | Integer | `90` | | `compute_instance_group_multiple_zones` | `mig_min_zones` | Integer | `2` | | `compute_public_address_shodan` | `shodan_api_key` | String | `null` | | `compute_snapshot_not_outdated` | `max_snapshot_age_days` | Integer | `90` | | `iam_sa_user_managed_key_unused` | `max_unused_account_days` | Integer | `180` | | `iam_service_account_unused` | `max_unused_account_days` | Integer | `180` | | `secretmanager_secret_rotation_enabled` | `secretmanager_max_rotation_days` | Integer | `90` | ## Kubernetes ### Configurable Checks The following list includes all the Kubernetes checks with configurable variables that can be changed in the configuration yaml file: | Check Name | Value | Type | Default | | - | - | - | - | | `apiserver_audit_log_maxage_set` | `audit_log_maxage` | Integer | `30` | | `apiserver_audit_log_maxbackup_set` | `audit_log_maxbackup` | Integer | `10` | | `apiserver_audit_log_maxsize_set` | `audit_log_maxsize` | Integer | `100` | | `apiserver_strong_ciphers_only` | `apiserver_strong_ciphers` | List of Strings | `["TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"]` | | `kubelet_strong_ciphers_only` | `kubelet_strong_ciphers` | List of Strings | See `config.yaml` | ## M365 ### Configurable Checks The following list includes all the Microsoft 365 checks with configurable variables that can be changed in the configuration yaml file: | Check Name | Value | Type | Default | | - | - | - | - | | `defender_malware_policy_comprehensive_attachments_filter_applied` | `recommended_blocked_file_types` | List of Strings | See check defaults | | `entra_admin_users_sign_in_frequency_enabled` | `sign_in_frequency` | Integer | `4` | | `exchange_organization_mailtips_enabled` | `recommended_mailtips_large_audience_threshold` | Integer | `25` | | `exchange_user_mailbox_auditing_enabled` | `audit_log_age` | Integer | `90` | | `teams_external_file_sharing_restricted` | `allowed_cloud_storage_services` | List of Strings | `[]` | ## GitHub ### Configurable Checks The following list includes all the GitHub checks with configurable variables that can be changed in the configuration yaml file: | Check Name | Value | Type | Default | | - | - | - | - | | `repository_inactive_not_archived` | `inactive_not_archived_days_threshold` | Integer | `180` | ## Vercel ### Configurable Checks The following list includes all the Vercel checks with configurable variables that can be changed in the configuration YAML file: | Check Name | Value | Type | Default | | - | - | - | - | | `authentication_no_stale_tokens` | `stale_token_threshold_days` | Integer | `90` | | `authentication_token_not_expired` | `days_to_expire_threshold` | Integer | `7` | | `deployment_production_uses_stable_target` | `stable_branches` | List of Strings | `["main", "master"]` | | `domain_ssl_certificate_valid` | `days_to_expire_threshold` | Integer | `7` | | `project_environment_no_secrets_in_plain_type` | `secret_suffixes` | List of Strings | `["_KEY", "_SECRET", "_TOKEN", "_PASSWORD", "_API_KEY", "_PRIVATE_KEY"]` | | `project_environment_no_secrets_with_public_prefix` | `secret_suffixes` | List of Strings | `["_KEY", "_SECRET", "_TOKEN", "_PASSWORD", "_API_KEY", "_PRIVATE_KEY"]` | | `project_environment_no_secrets_with_public_prefix` | `public_env_prefixes` | List of Strings | `["NEXT_PUBLIC_", "NUXT_PUBLIC_", "VITE_", "REACT_APP_", "VUE_APP_", "GATSBY_", "EXPO_PUBLIC_", "PUBLIC_"]` | | `team_member_role_least_privilege` | `max_owner_percentage` | Integer | `20` | | `team_member_role_least_privilege` | `max_owners` | Integer | `3` | | `team_no_stale_invitations` | `stale_invitation_threshold_days` | Integer | `30` | ## Okta ### Configurable Checks The following list includes all the Okta checks with configurable variables that can be changed in the configuration YAML file: | Check Name | Value | Type | Default | | - | - | - | - | | `application_admin_console_session_idle_timeout_15min` | `okta_admin_console_idle_timeout_max_minutes` | Integer | `15` | | `idp_smart_card_dod_approved_ca` | `okta_dod_approved_ca_issuer_patterns` | List of Strings | `[]` | | `signon_global_session_idle_timeout_15min` | `okta_max_session_idle_minutes` | Integer | `15` | | `signon_global_session_lifetime_18h` | `okta_max_session_lifetime_minutes` | Integer | `1080` | | `user_inactivity_automation_35d_enabled` | `okta_user_inactivity_max_days` | Integer | `35` | ## Alibaba Cloud ### Configurable Checks The following list includes all the Alibaba Cloud checks with configurable variables that can be changed in the configuration YAML file: | Check Name | Value | Type | Default | | - | - | - | - | | `cs_kubernetes_cluster_check_recent` | `max_cluster_check_days` | Integer | `7` | | `cs_kubernetes_cluster_check_weekly` | `max_cluster_check_days` | Integer | `7` | | `ram_user_console_access_unused` | `max_console_access_days` | Integer | `90` | | `rds_instance_sql_audit_retention` | `min_rds_audit_retention_days` | Integer | `180` | | `sls_logstore_retention_period` | `min_log_retention_days` | Integer | `365` | ## MongoDB Atlas ### Configurable Checks The following list includes all the MongoDB Atlas checks with configurable variables that can be changed in the configuration YAML file: | Check Name | Value | Type | Default | | - | - | - | - | | `organizations_service_account_secrets_expiration` | `max_service_account_secret_validity_hours` | Integer | `8` | ## OpenStack ### Configurable Checks The following list includes all the OpenStack checks with configurable variables that can be changed in the configuration YAML file: | Check Name | Value | Type | Default | | - | - | - | - | | `blockstorage_snapshot_metadata_sensitive_data` | `secrets_ignore_patterns` | List of Strings | `[]` | | `blockstorage_volume_metadata_sensitive_data` | `secrets_ignore_patterns` | List of Strings | `[]` | | `compute_instance_metadata_sensitive_data` | `secrets_ignore_patterns` | List of Strings | `[]` | | `image_not_shared_with_multiple_projects` | `image_sharing_threshold` | Integer | `5` | | `objectstorage_container_metadata_sensitive_data` | `secrets_ignore_patterns` | List of Strings | `[]` | ## Config YAML File Structure > [!NOTE] > > This is the new Prowler configuration file format. The old one without provider keys is still compatible just for the AWS provider. ```yaml title="config.yaml" theme={null} # AWS Configuration aws: # AWS Global Configuration # aws.mute_non_default_regions --> Set to True to muted failed findings in non-default regions for AccessAnalyzer, GuardDuty, SecurityHub, DRS and Config mute_non_default_regions: False # AWS Resource Scan Limit Configuration # Disabled by default: scan every resource unless a positive limit is configured. # Findings are not capped. Set to 0 (or a negative value) to disable the limit. # aws.max_scanned_resources_per_service --> global default for all services below max_scanned_resources_per_service: 0 # Per-service overrides. Leave as null to fall back to the global default. max_ebs_snapshots: null max_backup_recovery_points: null max_cloudwatch_log_groups: null max_lambda_functions: null max_ecs_task_definitions: null max_codeartifact_packages: null # If you want to mute failed findings only in specific regions, create a file with the following syntax and run it with `prowler aws -w mutelist.yaml`: # Mutelist: # Accounts: # "*": # Checks: # "*": # Regions: # - "ap-southeast-1" # - "ap-southeast-2" # Resources: # - "*" # AWS IAM Configuration # aws.iam_user_accesskey_unused --> CIS recommends 45 days max_unused_access_keys_days: 45 # aws.iam_user_console_access_unused --> CIS recommends 45 days max_console_access_days: 45 # aws.iam_user_access_not_stale_to_sagemaker --> default 90 days max_unused_sagemaker_access_days: 90 # AWS EC2 Configuration # aws.ec2_elastic_ip_shodan # TODO: create common config shodan_api_key: null # aws.ec2_securitygroup_with_many_ingress_egress_rules --> by default is 50 rules max_security_group_rules: 50 # aws.ec2_instance_older_than_specific_days --> by default is 6 months (180 days) max_ec2_instance_age_in_days: 180 # aws.ec2_instance_stopped_older_than_specific_days --> by default is 30 days max_ec2_instance_stopped_days: 30 # aws.ec2_securitygroup_allow_ingress_from_internet_to_any_port # allowed network interface types for security groups open to the Internet ec2_allowed_interface_types: [ "api_gateway_managed", "vpc_endpoint", ] # allowed network interface owners for security groups open to the Internet ec2_allowed_instance_owners: [ "amazon-elb" ] # aws.ec2_securitygroup_allow_ingress_from_internet_to_high_risk_tcp_ports ec2_high_risk_ports: [ 25, 110, 135, 143, 445, 3000, 4333, 5000, 5500, 8080, 8088, ] # AWS VPC Configuration (vpc_endpoint_connections_trust_boundaries, vpc_endpoint_services_allowed_principals_trust_boundaries) # AWS SSM Configuration (ssm_documents_set_as_public) # AWS S3 Configuration (s3_bucket_cross_account_access) # AWS EventBridge Configuration (eventbridge_schema_registry_cross_account_access, eventbridge_bus_cross_account_access) # AWS DynamoDB Configuration (dynamodb_table_cross_account_access) # Single account environment: No action required. The AWS account number will be automatically added by the checks. # Multi account environment: Any additional trusted account number should be added as a space separated list, e.g. # trusted_account_ids : ["123456789012", "098765432109", "678901234567"] trusted_account_ids: [] # AWS Cloudwatch Configuration # aws.cloudwatch_log_group_retention_policy_specific_days_enabled --> by default is 365 days log_group_retention_days: 365 # AWS AppStream Session Configuration # aws.appstream_fleet_session_idle_disconnect_timeout max_idle_disconnect_timeout_in_seconds: 600 # 10 Minutes # aws.appstream_fleet_session_disconnect_timeout max_disconnect_timeout_in_seconds: 300 # 5 Minutes # aws.appstream_fleet_maximum_session_duration max_session_duration_seconds: 36000 # 10 Hours # AWS Elastic Beanstalk Configuration # aws.elasticbeanstalk_environment_php_platform_updated # Oldest PHP branch still receiving security fixes elasticbeanstalk_php_min_branch: "8.2" # Oldest Amazon Linux 2023 PHP platform version bundling the fixed PHP release elasticbeanstalk_php_min_platform_version: "4.13.13" # AWS Lightsail Configuration # aws.lightsail_instance_php_blueprint_updated # Blueprint id prefixes that ship PHP and require manual runtime verification lightsail_php_blueprints: [ "wordpress", "lamp", "nginx", "drupal", "joomla", "magento", "prestashop", "plesk", "cpanel", ] # AWS Lambda Configuration # aws.awslambda_function_using_supported_runtimes obsolete_lambda_runtimes: [ "java8", "go1.x", "provided", "python3.6", "python2.7", "python3.7", "nodejs4.3", "nodejs4.3-edge", "nodejs6.10", "nodejs", "nodejs8.10", "nodejs10.x", "nodejs12.x", "nodejs14.x", "dotnet5.0", "dotnetcore1.0", "dotnetcore2.0", "dotnetcore2.1", "dotnetcore3.1", "ruby2.5", "ruby2.7", ] # AWS Organizations # aws.organizations_scp_check_deny_regions # aws.organizations_enabled_regions: [ # "eu-central-1", # "eu-west-1", # "us-east-1" # ] organizations_enabled_regions: [] organizations_trusted_delegated_administrators: [] # AWS ECR # aws.ecr_repositories_scan_vulnerabilities_in_latest_image # CRITICAL # HIGH # MEDIUM ecr_repository_vulnerability_minimum_severity: "MEDIUM" # AWS Inspector2 # aws.inspector2_coverage_recently_scanned # Maximum days since Inspector2 last scanned an actively covered resource inspector2_max_days_since_last_scan: 3 # aws.inspector2_active_findings_within_max_age # Maximum days an Inspector2 finding can stay active since it was first observed inspector2_active_finding_max_age_days: 192 # AWS Trusted Advisor # aws.trustedadvisor_premium_support_plan_subscribed verify_premium_support_plans: True # AWS CloudTrail Configuration # aws.cloudtrail_threat_detection_privilege_escalation threat_detection_privilege_escalation_threshold: 0.2 # Percentage of actions found to decide if it is a privilege_escalation attack event, by default is 0.2 (20%) threat_detection_privilege_escalation_minutes: 1440 # Past minutes to search from now for privilege_escalation attacks, by default is 1440 minutes (24 hours) threat_detection_privilege_escalation_actions: [ "AddPermission", "AddRoleToInstanceProfile", "AddUserToGroup", "AssociateAccessPolicy", "AssumeRole", "AttachGroupPolicy", "AttachRolePolicy", "AttachUserPolicy", "ChangePassword", "CreateAccessEntry", "CreateAccessKey", "CreateDevEndpoint", "CreateEventSourceMapping", "CreateFunction", "CreateGroup", "CreateJob", "CreateKeyPair", "CreateLoginProfile", "CreatePipeline", "CreatePolicyVersion", "CreateRole", "CreateStack", "DeleteRolePermissionsBoundary", "DeleteRolePolicy", "DeleteUserPermissionsBoundary", "DeleteUserPolicy", "DetachRolePolicy", "DetachUserPolicy", "GetCredentialsForIdentity", "GetId", "GetPolicyVersion", "GetUserPolicy", "Invoke", "ModifyInstanceAttribute", "PassRole", "PutGroupPolicy", "PutPipelineDefinition", "PutRolePermissionsBoundary", "PutRolePolicy", "PutUserPermissionsBoundary", "PutUserPolicy", "ReplaceIamInstanceProfileAssociation", "RunInstances", "SetDefaultPolicyVersion", "UpdateAccessKey", "UpdateAssumeRolePolicy", "UpdateDevEndpoint", "UpdateEventSourceMapping", "UpdateFunctionCode", "UpdateJob", "UpdateLoginProfile", ] # aws.cloudtrail_threat_detection_enumeration threat_detection_enumeration_threshold: 0.3 # Percentage of actions found to decide if it is an enumeration attack event, by default is 0.3 (30%) threat_detection_enumeration_minutes: 1440 # Past minutes to search from now for enumeration attacks, by default is 1440 minutes (24 hours) threat_detection_enumeration_actions: [ "DescribeAccessEntry", "DescribeAccountAttributes", "DescribeAvailabilityZones", "DescribeBundleTasks", "DescribeCarrierGateways", "DescribeClientVpnRoutes", "DescribeCluster", "DescribeDhcpOptions", "DescribeFlowLogs", "DescribeImages", "DescribeInstanceAttribute", "DescribeInstanceInformation", "DescribeInstanceTypes", "DescribeInstances", "DescribeInstances", "DescribeKeyPairs", "DescribeLogGroups", "DescribeLogStreams", "DescribeOrganization", "DescribeRegions", "DescribeSecurityGroups", "DescribeSnapshotAttribute", "DescribeSnapshotTierStatus", "DescribeSubscriptionFilters", "DescribeTransitGatewayMulticastDomains", "DescribeVolumes", "DescribeVolumesModifications", "DescribeVpcEndpointConnectionNotifications", "DescribeVpcs", "GetAccount", "GetAccountAuthorizationDetails", "GetAccountSendingEnabled", "GetBucketAcl", "GetBucketLogging", "GetBucketPolicy", "GetBucketReplication", "GetBucketVersioning", "GetCallerIdentity", "GetCertificate", "GetConsoleScreenshot", "GetCostAndUsage", "GetDetector", "GetEbsDefaultKmsKeyId", "GetEbsEncryptionByDefault", "GetFindings", "GetFlowLogsIntegrationTemplate", "GetIdentityVerificationAttributes", "GetInstances", "GetIntrospectionSchema", "GetLaunchTemplateData", "GetLaunchTemplateData", "GetLogRecord", "GetParameters", "GetPolicyVersion", "GetPublicAccessBlock", "GetQueryResults", "GetRegions", "GetSMSAttributes", "GetSMSSandboxAccountStatus", "GetSendQuota", "GetTransitGatewayRouteTableAssociations", "GetUserPolicy", "HeadObject", "ListAccessKeys", "ListAccounts", "ListAllMyBuckets", "ListAssociatedAccessPolicies", "ListAttachedUserPolicies", "ListClusters", "ListDetectors", "ListDomains", "ListFindings", "ListHostedZones", "ListIPSets", "ListIdentities", "ListInstanceProfiles", "ListObjects", "ListOrganizationalUnitsForParent", "ListOriginationNumbers", "ListPolicyVersions", "ListRoles", "ListRoles", "ListRules", "ListServiceQuotas", "ListSubscriptions", "ListTargetsByRule", "ListTopics", "ListUsers", "LookupEvents", "Search", ] # aws.cloudtrail_threat_detection_llm_jacking threat_detection_llm_jacking_threshold: 0.4 # Percentage of actions found to decide if it is an LLM Jacking attack event, by default is 0.4 (40%) threat_detection_llm_jacking_minutes: 1440 # Past minutes to search from now for LLM Jacking attacks, by default is 1440 minutes (24 hours) threat_detection_llm_jacking_actions: [ "PutUseCaseForModelAccess", # Submits a use case for model access, providing justification (Write). "PutFoundationModelEntitlement", # Grants entitlement for accessing a foundation model (Write). "PutModelInvocationLoggingConfiguration", # Configures logging for model invocations (Write). "CreateFoundationModelAgreement", # Creates a new agreement to use a foundation model (Write). "InvokeModel", # Invokes a specified Bedrock model for inference using provided prompt and parameters (Read). "InvokeModelWithResponseStream", # Invokes a Bedrock model for inference with real-time token streaming (Read). "GetUseCaseForModelAccess", # Retrieves an existing use case for model access (Read). "GetModelInvocationLoggingConfiguration", # Fetches the logging configuration for model invocations (Read). "GetFoundationModelAvailability", # Checks the availability of a foundation model for use (Read). "ListFoundationModelAgreementOffers", # Lists available agreement offers for accessing foundation models (List). "ListFoundationModels", # Lists the available foundation models in Bedrock (List). "ListProvisionedModelThroughputs", # Lists the provisioned throughput for previously created models (List). ] # AWS RDS Configuration # aws.rds_instance_backup_enabled # Whether to check RDS instance replicas or not check_rds_instance_replicas: False # AWS ACM Configuration # aws.acm_certificates_expiration_check days_to_expire_threshold: 7 # AWS EKS Configuration # aws.eks_control_plane_logging_all_types_enabled # EKS control plane logging types that must be enabled eks_required_log_types: [ "api", "audit", "authenticator", "controllerManager", "scheduler", ] # aws.eks_cluster_uses_a_supported_version # EKS clusters must be version 1.28 or higher eks_cluster_oldest_version_supported: "1.28" # AWS CodeBuild Configuration # aws.codebuild_project_no_secrets_in_variables # CodeBuild sensitive variables that are excluded from the check excluded_sensitive_environment_variables: [ ] # Azure Configuration azure: # Azure Network Configuration # azure.network_public_ip_shodan # TODO: create common config shodan_api_key: null # Azure App Service # Minimum runtime versions; any newer version passes # azure.app_ensure_php_version_is_latest php_latest_version: "8.5" # azure.app_ensure_python_version_is_latest python_latest_version: "3.12" # azure.app_ensure_java_version_is_latest java_latest_version: "17" # Azure SQL Server # azure.sqlserver_minimal_tls_version recommended_minimal_tls_versions: [ "1.2", "1.3" ] # Azure Storage # azure.storage_smb_channel_encryption_with_secure_algorithm # List of SMB channel encryption algorithms allowed on file shares. A storage # account passes only if every enabled algorithm is in this list. Defaults to # the value required by CIS (AES-256-GCM only, excluding weaker AES-128 ciphers). recommended_smb_channel_encryption_algorithms: [ "AES-256-GCM", # "AES-128-CCM", # "AES-128-GCM", ] # Azure Virtual Machines # azure.vm_desired_sku_size # List of desired VM SKU sizes that are allowed in the organization desired_vm_sku_sizes: [ "Standard_A8_v2", "Standard_DS3_v2", "Standard_D4s_v3", ] # Azure VM Backup Configuration # azure.vm_sufficient_daily_backup_retention_period vm_backup_min_daily_retention_days: 7 # Azure API Management Threat Detection Configuration # azure.apim_threat_detection_llm_jacking apim_threat_detection_llm_jacking_threshold: 0.1 apim_threat_detection_llm_jacking_minutes: 1440 apim_threat_detection_llm_jacking_actions: [ # OpenAI API endpoints "ImageGenerations_Create", "ChatCompletions_Create", "Completions_Create", "Embeddings_Create", "FineTuning_Jobs_Create", "Models_List", # Azure OpenAI endpoints "Deployments_List", "Deployments_Get", "Deployments_Create", "Deployments_Delete", # Anthropic endpoints "Messages_Create", "Claude_Create", # Google AI endpoints "GenerateContent", "GenerateText", "GenerateImage", # Meta AI endpoints "Llama_Create", "CodeLlama_Create", # Other LLM endpoints "Gemini_Generate", "Claude_Generate", "Llama_Generate" ] # GCP Configuration gcp: # GCP Compute Configuration # gcp.compute_public_address_shodan shodan_api_key: null # gcp.compute_configuration_changes # Number of days to look back for Compute Engine configuration changes in audit logs compute_audit_log_lookback_days: 1 # gcp.compute_instance_group_multiple_zones # Minimum number of zones a MIG should span for high availability mig_min_zones: 2 # Kubernetes Configuration kubernetes: # Kubernetes API Server # kubernetes.apiserver_audit_log_maxbackup_set audit_log_maxbackup: 10 # kubernetes.apiserver_audit_log_maxsize_set audit_log_maxsize: 100 # kubernetes.apiserver_audit_log_maxage_set audit_log_maxage: 30 # kubernetes.apiserver_strong_ciphers_only apiserver_strong_ciphers: [ "TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", ] # Kubelet # kubernetes.kubelet_strong_ciphers_only kubelet_strong_ciphers: [ "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "TLS_RSA_WITH_AES_256_GCM_SHA384", "TLS_RSA_WITH_AES_128_GCM_SHA256", ] # M365 Configuration m365: # Entra Conditional Access Policy # m365.entra_admin_users_sign_in_frequency_enabled sign_in_frequency: 4 # 4 hours # Teams Settings # m365.teams_external_file_sharing_restricted allowed_cloud_storage_services: [ #"allow_box", #"allow_drop_box", #"allow_egnyte", #"allow_google_drive", #"allow_share_file", ] # Exchange Organization Settings # m365.exchange_organization_mailtips_enabled recommended_mailtips_large_audience_threshold: 25 # maximum number of recipients # GitHub Configuration github: # github.repository_inactive_not_archived inactive_not_archived_days_threshold: 180 # Vercel Configuration vercel: # vercel.deployment_production_uses_stable_target stable_branches: - "main" - "master" # vercel.authentication_token_not_expired & vercel.domain_ssl_certificate_valid days_to_expire_threshold: 7 # vercel.authentication_no_stale_tokens stale_token_threshold_days: 90 # vercel.team_no_stale_invitations stale_invitation_threshold_days: 30 # vercel.team_member_role_least_privilege max_owner_percentage: 20 max_owners: 3 # vercel.project_environment_no_secrets_in_plain_type & vercel.project_environment_no_secrets_with_public_prefix secret_suffixes: - "_KEY" - "_SECRET" - "_TOKEN" - "_PASSWORD" - "_API_KEY" - "_PRIVATE_KEY" # vercel.project_environment_no_secrets_with_public_prefix public_env_prefixes: - "NEXT_PUBLIC_" - "NUXT_PUBLIC_" - "VITE_" - "REACT_APP_" - "VUE_APP_" - "GATSBY_" - "EXPO_PUBLIC_" - "PUBLIC_" ``` # Custom Checks Metadata Source: https://docs.prowler.com/user-guide/cli/tutorials/custom-checks-metadata In certain organizations, the severity of specific checks might differ from the default values defined in the check's metadata. For instance, while `s3_bucket_level_public_access_block` could be deemed `critical` for some organizations, others might assign a different severity level to it. The custom metadata option offers a means to override default metadata set by Prowler. You can use `--custom-checks-metadata-file` followed by the path to your custom checks metadata YAML file. ## Available Fields The list of supported check's metadata fields that can be overridden are listed as follows: * Severity * CheckTitle * Risk * RelatedUrl * Remediation * Code * CLI * NativeIaC * Other * Terraform * Recommendation * Text * Url ## File Syntax This feature is available for all the providers supported in Prowler since the metadata format is common between all the providers. The YAML format for the custom checks metadata file is as follows: ```yaml title="custom_checks_metadata.yaml" theme={null} CustomChecksMetadata: aws: Checks: s3_bucket_level_public_access_block: Severity: high CheckTitle: S3 Bucket Level Public Access Block Description: This check ensures that the S3 bucket level public access block is enabled. Risk: This check is important because it ensures that the S3 bucket level public access block is enabled. RelatedUrl: https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html Remediation: Code: CLI: aws s3api put-public-access-block --bucket --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true NativeIaC: https://aws.amazon.com/es/s3/features/block-public-access/ Other: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html Terraform: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_public_access_block Recommendation: Text: Enable the S3 bucket level public access block. Url: https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html s3_bucket_no_mfa_delete: Severity: high CheckTitle: S3 Bucket No MFA Delete Description: This check ensures that the S3 bucket does not allow delete operations without MFA. Risk: This check is important because it ensures that the S3 bucket does not allow delete operations without MFA. RelatedUrl: https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html Remediation: Code: CLI: aws s3api put-bucket-versioning --bucket --versioning-configuration Status=Enabled,MFADelete=Enabled NativeIaC: https://aws.amazon.com/es/s3/features/versioning/ Other: https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html Terraform: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_versioning Recommendation: Text: Enable versioning on the S3 bucket. Url: https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html azure: Checks: storage_infrastructure_encryption_is_enabled: Severity: medium CheckTitle: Storage Infrastructure Encryption Is Enabled Description: This check ensures that storage infrastructure encryption is enabled. Risk: This check is important because it ensures that storage infrastructure encryption is enabled. RelatedUrl: https://docs.microsoft.com/en-us/azure/storage/common/storage-service-encryption Remediation: Code: CLI: az storage account update --name --resource-group --set properties.encryption.services.blob.enabled=true properties.encryption.services.file.enabled=true properties.encryption.services.queue.enabled=true properties.encryption.services.table.enabled=true NativeIaC: https://docs.microsoft.com/en-us/azure/templates/microsoft.storage/storageaccounts Other: https://docs.microsoft.com/en-us/azure/storage/common/storage-service-encryption Terraform: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_account Recommendation: Text: Enable storage infrastructure encryption. Url: https://docs.microsoft.com/en-us/azure/storage/common/storage-service-encryption gcp: Checks: compute_instance_public_ip: Severity: critical CheckTitle: Compute Instance Public IP Description: This check ensures that the compute instance does not have a public IP. Risk: This check is important because it ensures that the compute instance does not have a public IP. RelatedUrl: https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address Remediation: Code: CLI: https://docs.prowler.com/checks/gcp/google-cloud-public-policies/bc_gcp_public_2#cli-command NativeIaC: https://cloud.google.com/compute/docs/reference/rest/v1/instances Other: https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address Terraform: https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance Recommendation: Text: Remove the public IP from the compute instance. Url: https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address kubernetes: Checks: apiserver_anonymous_requests: Severity: low CheckTitle: APIServer Anonymous Requests Description: This check ensures that anonymous requests to the APIServer are disabled. Risk: This check is important because it ensures that anonymous requests to the APIServer are disabled. RelatedUrl: https://kubernetes.io/docs/reference/access-authn-authz/authentication/ Remediation: Code: CLI: --anonymous-auth=false NativeIaC: https://docs.prowler.com/checks/kubernetes/kubernetes-policy-index/ensure-that-the-anonymous-auth-argument-is-set-to-false-1#kubernetes Other: https://kubernetes.io/docs/reference/access-authn-authz/authentication/ Terraform: https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/cluster_role_binding Recommendation: Text: Disable anonymous requests to the APIServer. Url: https://kubernetes.io/docs/reference/access-authn-authz/authentication/ ``` ## Usage Executing the following command will assess all checks and generate a report while overriding the metadata for those checks: ```sh theme={null} prowler --custom-checks-metadata-file ``` This customization feature enables organizations to tailor the severity of specific checks based on their unique requirements, providing greater flexibility in security assessment and reporting. # Prowler Local Dashboard Source: https://docs.prowler.com/user-guide/cli/tutorials/dashboard Prowler Local Dashboard is a local web dashboard built from the CSV outputs produced by Prowler CLI. Launch it with: ```sh theme={null} prowler dashboard ``` > [!NOTE] > > You can expose the `dashboard` server in another address using the `HOST` environment variable. To run Prowler Local Dashboard with Docker, use: ```sh theme={null} docker run -v /your/local/dir/prowler-output:/home/prowler/output --env HOST=0.0.0.0 --publish 127.0.0.1:11666:11666 toniblyx/prowler:latest dashboard ``` Make sure you update the `/your/local/dir/prowler-output` to match the path that contains your prowler output. > [!NOTE] > > **Remember that the `dashboard` server is not authenticated. If you expose it to the Internet, do it at your own risk.** The console shows the dashboard version, the directory the CSV files are loaded from, the local URL once the server is listening, and a short note about bringing your findings to Prowler Cloud. Set `PROWLER_NO_PROMOTIONS=1` to omit that note: ```sh theme={null} PROWLER_NO_PROMOTIONS=1 prowler dashboard ``` Set `NO_COLOR=1` to print the startup output without colors. ## Overview Page The overview page provides a full impression of your findings obtained from Prowler: ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/dashboard/dashboard-overview.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=ae182f631733f87545c9155a0f977928) This page allows for multiple functions: * Apply filters: * Assessment Date * Account * Region * Severity * Service * Provider * Status * Category * See which files have been scanned to generate the dashboard by placing your mouse on the `?` icon: ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/dashboard/dashboard-files-scanned.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=30c6fcb723a0d6a22d0684bcbe8f4e6a) * Download the `Top Findings by Severity` table using the button `DOWNLOAD THIS TABLE AS CSV` or `DOWNLOAD THIS TABLE AS XLSX` * Click the provider cards to filter by provider. * On the dropdowns under `Top Findings by Severity` you can apply multiple sorts to see the information, also you will get a detailed view of each finding using the dropdowns: ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/dashboard/dropdown.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=08abd919af7d869e122020838c60d79b) ## Compliance Page This page shows all the info related to the compliance selected. Multiple filters can be selected as per your preferences. ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/dashboard/dashboard-compliance.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=b5ee940817f2c66d7866903dc4b7ac38) To add your own compliance to compliance page, add a file with the compliance name (using `_` instead of `.`) to the path `/dashboard/compliance`. In this file use the format present in the other compliance files to create the table. Example for CIS 2.0: ```python theme={null} import warnings from dashboard.common_methods import get_section_containers_cis warnings.filterwarnings("ignore") def get_table(data): aux = data[ [ "REQUIREMENTS_ID", "REQUIREMENTS_DESCRIPTION", "REQUIREMENTS_ATTRIBUTES_SECTION", "CHECKID", "STATUS", "REGION", "ACCOUNTID", "RESOURCEID", ] ].copy() return get_section_containers_cis( aux, "REQUIREMENTS_ID", "REQUIREMENTS_ATTRIBUTES_SECTION" ) ``` ## S3 Integration If you are using Prowler Cloud with the S3 integration or that integration from Prowler CLI and you want to use your data from your S3 bucket, you can run the following command to load the dashboard with the new files: ```sh theme={null} aws s3 cp s3:///output/csv ./output --recursive ``` ## Output Path Prowler will use the outputs from the folder `/output` (for common prowler outputs) and `/output/compliance` (for prowler compliance outputs) to generate the dashboard. To change the path, modify the values `folder_path_overview` or `folder_path_compliance` from `/dashboard/config.py` > [!NOTE] > > If you have any issue related with dashboards, check that the output path where the dashboard is getting the outputs is correct. ## Output Support Prowler dashboard supports the detailed outputs: | Provider | V3 | V4 | COMPLIANCE-V3 | COMPLIANCE-V4 | | - | - | - | - | - | | AWS | ✅ | ✅ | ✅ | ✅ | | Azure | ❌ | ✅ | ❌ | ✅ | | Kubernetes | ❌ | ✅ | ❌ | ✅ | | GCP | ❌ | ✅ | ❌ | ✅ | | M365 | ❌ | ✅ | ❌ | ✅ | | GitHub | ❌ | ✅ | ❌ | ✅ | # Prowler Fixers (Remediations) Source: https://docs.prowler.com/user-guide/cli/tutorials/fixer Prowler allows you to fix some of the failed findings it identifies. You can use the `--fixer` flag to run the fixes that are available for the checks that failed. ```sh theme={null} prowler -c ... --fixer ``` ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/fixer.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=6e536fb9f787897abf35684e89769fca) > [!NOTE] > > You can see all the available fixes for each provider with the `--list-remediations` or `--list-fixers` flag. > > ```sh theme={null} > prowler --list-fixers > ``` It's important to note that using the fixers for `Access Analyzer`, `GuardDuty`, and `SecurityHub` may incur additional costs. These AWS services might trigger actions or deploy resources that can lead to charges on your AWS account. ## Writing a Fixer To write a fixer, you need to create a file called `_fixer.py` inside the check folder, with a function called `fixer` that receives either the region or the resource to be fixed as a parameter, and returns a boolean value indicating if the fix was successful or not. For example, the regional fixer for the `ec2_ebs_default_encryption` check, which enables EBS encryption by default in a region, would look like this: ```python theme={null} from prowler.lib.logger import logger from prowler.providers.aws.services.ec2.ec2_client import ec2_client def fixer(region): """ Enable EBS encryption by default in a region. Note: Custom KMS keys for EBS Default Encryption may be overwritten. Requires the ec2:EnableEbsEncryptionByDefault permission. It can be set as follows: { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ec2:EnableEbsEncryptionByDefault", "Resource": "*" } ] } Args: region (str): AWS region Returns: bool: True if EBS encryption by default is enabled, False otherwise """ try: regional_client = ec2_client.regional_clients[region] return regional_client.enable_ebs_encryption_by_default()[ "EbsEncryptionByDefault" ] except Exception as error: logger.error( f"{region} -- {error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) return False ``` On the other hand, the fixer for the `s3_account_level_public_access_blocks` check, which enables the account-level public access blocks for S3, would look like this: ```python theme={null} from prowler.lib.logger import logger from prowler.providers.aws.services.s3.s3control_client import s3control_client def fixer(resource_id: str) -> bool: """ Enable S3 Block Public Access for the account. Note: Custom KMS keys for EBS Default Encryption may be overwritten. By blocking all S3 public access you may break public S3 buckets. Requires the s3:PutAccountPublicAccessBlock permission: { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:PutAccountPublicAccessBlock", "Resource": "*" } ] } Returns: bool: True if S3 Block Public Access is enabled, False otherwise """ try: s3control_client.client.put_public_access_block( AccountId=resource_id, PublicAccessBlockConfiguration={ "BlockPublicAcls": True, "IgnorePublicAcls": True, "BlockPublicPolicy": True, "RestrictPublicBuckets": True, }, ) except Exception as error: logger.error( f"{error.__class__.__name__}[{error.__traceback__.tb_lineno}]: {error}" ) return False else: return True ``` ## Fixer Config File For some fixers, you can have configurable parameters depending on your use case. You can either use the default config file in `prowler/config/fixer_config.yaml` or create a custom config file and pass it to the fixer with the `--fixer-config` flag. The config file should be a YAML file with the following structure: ```yaml theme={null} # Fixer configuration file aws: # ec2_ebs_default_encryption # No configuration needed for this check # s3_account_level_public_access_blocks # No configuration needed for this check # iam_password_policy_* checks: iam_password_policy: MinimumPasswordLength: 14 RequireSymbols: True RequireNumbers: True RequireUppercaseCharacters: True RequireLowercaseCharacters: True AllowUsersToChangePassword: True MaxPasswordAge: 90 PasswordReusePrevention: 24 HardExpiry: False # accessanalyzer_enabled accessanalyzer_enabled: AnalyzerName: "DefaultAnalyzer" AnalyzerType: "ACCOUNT_UNUSED_ACCESS" # guardduty_is_enabled # No configuration needed for this check # securityhub_enabled securityhub_enabled: EnableDefaultStandards: True # cloudtrail_multi_region_enabled cloudtrail_multi_region_enabled: TrailName: "DefaultTrail" S3BucketName: "my-cloudtrail-bucket" IsMultiRegionTrail: True EnableLogFileValidation: True # CloudWatchLogsLogGroupArn: "arn:aws:logs:us-east-1:123456789012:log-group:my-cloudtrail-log-group" # CloudWatchLogsRoleArn: "arn:aws:iam::123456789012:role/my-cloudtrail-role" # KmsKeyId: "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" # kms_cmk_rotation_enabled # No configuration needed for this check # ec2_ebs_snapshot_account_block_public_access ec2_ebs_snapshot_account_block_public_access: State: "block-all-sharing" # ec2_instance_account_imdsv2_enabled # No configuration needed for this check ``` # Integrations Source: https://docs.prowler.com/user-guide/cli/tutorials/integrations ## Integration with Slack Prowler can be integrated with [Slack](https://slack.com/) to send a summary of the execution having configured a Slack APP in your channel with the following command: ```sh theme={null} prowler --slack ``` ![Prowler Slack Message](https://mintcdn.com/prowler/LI3palQgXkn4dRXg/images/cli/slack-prowler-message.png?fit=max\&auto=format\&n=LI3palQgXkn4dRXg\&q=85\&s=78899368e511d6bc4e1c69794b62c4ac) > [!NOTE] > > Slack integration needs `SLACK_API_TOKEN` and `SLACK_CHANNEL_NAME` environment variables. ### Configuration of the Integration with Slack To configure the Slack Integration, follow the next steps: 1. Create a Slack Application: * Go to [Slack API page](https://api.slack.com/tutorials/tracks/getting-a-token), scroll down to the *Create app* button and select your workspace: ![Create Slack App](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/create-slack-app.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=5a8f9fefa9c67dab8b45ad51c3aa9da6) * Install the application in your selected workspaces: ![Install Slack App in Workspace](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/install-in-slack-workspace.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=bf57e4fe599ccde26544e82cda3a5bd0) * Get the *Slack App OAuth Token* that Prowler needs to send the message: ![Slack App OAuth Token](https://mintcdn.com/prowler/LI3palQgXkn4dRXg/images/cli/slack-app-token.png?fit=max\&auto=format\&n=LI3palQgXkn4dRXg\&q=85\&s=30c40a4f6681a7407f118991663e37e6) 2. Optionally, create a Slack Channel (you can use an existing one) 3. Integrate the created Slack App to your Slack channel: * Click the channel, go to the Integrations tab, and Add an App. ![Slack App Channel Integration](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/integrate-slack-app.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=a863ba1f985a0945b2ec72192ace08fa) 4. Set the following environment variables that Prowler will read: * `SLACK_API_TOKEN`: the *Slack App OAuth Token* that was previously obtained. * `SLACK_CHANNEL_NAME`: the name of your Slack Channel where Prowler will send the message. # Logging Source: https://docs.prowler.com/user-guide/cli/tutorials/logging Prowler has a logging feature to be as transparent as possible, so that you can see every action that is being performed whilst the tool is being executed. ## Set Log Level There are different log levels depending on the logging information that is desired to be displayed: * **DEBUG**: It will show low-level logs from Python. * **INFO**: It will show all the API calls that are being invoked by the provider. * **WARNING**: It will show all resources that are being **muted**. * **ERROR**: It will show any errors, e.g., not authorized actions. * **CRITICAL**: The default log level. If a critical log appears, it will **exit** Prowler’s execution. You can establish the log level of Prowler with `--log-level` option: ```console theme={null} prowler --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} ``` > [!NOTE] > > By default, Prowler will run with the `CRITICAL` log level, since critical errors will abort the execution. ## Export Logs to File Prowler allows you to export the logs in json format with the `--log-file` option: ```console theme={null} prowler --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} --log-file .json ``` An example of a log file will be the following: ```json theme={null} { "timestamp": "2022-12-01 16:45:56,399", "filename": "ec2_service.py:114", "level": "ERROR", "module": "ec2_service", "message": "eu-west-2 -- ClientError[102]: An error occurred (UnauthorizedOperation) when calling the DescribeSecurityGroups operation: You are not authorized to perform this operation." } { "timestamp": "2022-12-01 16:45:56,438", "filename": "ec2_service.py:134", "level": "ERROR", "module": "ec2_service", "message": "eu-west-2 -- ClientError[124]: An error occurred (UnauthorizedOperation) when calling the DescribeNetworkAcls operation: You are not authorized to perform this operation." } ``` > [!NOTE] > > Each finding is represented as a `json` object. # Miscellaneous Source: https://docs.prowler.com/user-guide/cli/tutorials/misc ## Prowler Version ### Showing the Prowler Version ```console theme={null} prowler -V/-v/--version ``` ## Prowler Execution Options Prowler provides various execution settings. ### Verbose Execution To enable verbose mode in Prowler, similar to Version 2, use: ```console theme={null} prowler --verbose ``` ### Filter Findings by Status Prowler allows filtering findings based on their status, ensuring reports and CLI display only relevant findings: ```console theme={null} prowler --status [PASS, FAIL, MANUAL] ``` ### Disable Exit Code 3 By default, Prowler triggers exit code 3 for failed checks. To disable this behavior: ```console theme={null} prowler -z/--ignore-exit-code-3 ``` ### Hide Prowler Banner To run Prowler without displaying the banner: ```console theme={null} prowler -b/--no-banner ``` ### Disable Colors in Output To run Prowler without color formatting: ```console theme={null} prowler --no-color ``` ### Checks in Prowler Prowler provides various security checks per cloud provider. Use the following options to list, execute, or exclude specific checks: * **List Available Checks**: To display all available checks for the chosen provider: ```console theme={null} prowler --list-checks ``` * **Execute Specific Checks**: Run one or more specific security checks using: ```console theme={null} prowler -c/--checks s3_bucket_public_access ``` * **Exclude Specific Checks**: Exclude checks from execution with: ```console theme={null} prowler -e/--excluded-checks ec2 rds ``` * **Execute Checks from a JSON File**: To run checks defined in a JSON file, structure the file as follows: ```json theme={null} .json { "": [ " -C/--checks-file .json ``` ## Custom Checks in Prowler Prowler supports custom security checks, allowing users to define their own logic. ```console theme={null} prowler -x/--checks-folder ``` > [!NOTE] > > S3 URIs are also supported for custom check folders (e.g., `s3://bucket/prefix/checks_folder/`). Ensure the credentials used have `s3:GetObject` permissions in the specified S3 path. **Folder Structure for Custom Checks** Each check must reside in a dedicated subfolder, following this structure: * `__init__.py` (empty file) – Ensures Python treats the check folder as a package. * `check_name.py` (name file) – Defines the check’s logic for contextual information. * `check_name.metadata.json` (metadata file) – Defines the check’s metadata for contextual information. > [!NOTE] > > The check name must start with the service name followed by an underscore (e.g., ec2\_instance\_public\_ip). To see more information about how to write checks, refer to the [Developer Guide](/developer-guide/checks#creating-a-check). > [!NOTE] > > If you want to run ONLY your custom check(s), import it with -x (--checks-folder) and then run it with -c (--checks), e.g.: `console prowler aws -x s3://bucket/prowler/providers/aws/services/s3/s3_bucket_policy/ -c s3_bucket_policy` ## Severities Each of Prowler's checks has a severity, which can be one of the following: * informational * low * medium * high * critical To execute specific severity(s): ```console theme={null} prowler --severity critical high ``` ## Service Prowler has services per provider, there are options related with them: * List the available services in the provider: ```console theme={null} prowler --list-services ``` * Execute specific service(s): ```console theme={null} prowler -s/--services s3 iam ``` * Exclude specific service(s): ```console theme={null} prowler --excluded-services ec2 rds ``` ## Categories Prowler groups checks in different categories. There are options related with said categories: * List the available categories in the provider: ```console theme={null} prowler --list-categories ``` * Execute specific category(s): ```console theme={null} prowler --categories secrets ``` # Mutelisting Source: https://docs.prowler.com/user-guide/cli/tutorials/mutelist **Muting Findings for Intentional Configurations** In some cases, certain AWS resources may be intentionally configured in a way that deviates from security best practices but serves a valid use case. Examples include: An AWS S3 bucket open to the Internet, used for hosting a public website. An AWS security group with an open port necessary for a specific application. **Mutelist Option Behavior** The Mutelist option works in combination with other filtering mechanisms and modifies the output in the following way when a finding is muted: * JSON-OCSF: `status_id` is `Suppressed`. * CSV: `muted` is `True`. The field `status` will keep the original status, `MANUAL`, `PASS` or `FAIL`, of the finding. ## How the Mutelist Works The **Mutelist** uses **AND logic** to evaluate whether a finding should be muted. For a finding to be muted, **ALL** of the following conditions must match: * **Account** matches (exact match or `*`) * **Check** matches (exact match, regex pattern, or `*`) * **Region** matches (exact match, regex pattern, or `*`) * **Resource** matches (exact match, regex pattern, or `*`) * **Tags** match (if specified) If **any** of these criteria do not match, the finding is **not muted**. ### Tag Matching Logic Tags have special matching behavior: * **Multiple tags in the list = AND logic**: ALL tags must be present on the resource ```yaml theme={null} Tags: - "environment=dev" - "team=backend" # BOTH tags required ``` * **Regex alternation within a single tag = OR logic**: Use the pipe operator `|` for OR ```yaml theme={null} Tags: - "environment=dev|environment=stg" # Matches EITHER dev OR stg ``` * **Complex tag patterns**: Combine AND and OR using regex ```yaml theme={null} Tags: - "team=backend" # Required - "environment=dev|environment=stg" # AND (dev OR stg) ``` > [!NOTE] > > Remember that mutelist can be used with regular expressions. ## Mutelist Specification > [!NOTE] > > * For Azure provider, the Account ID is the Subscription Name and the Region is the Location. > * For GCP provider, the Account ID is the Project ID and the Region is the Zone. > * For Kubernetes provider, the Account ID is the Cluster Name and the Region is the Namespace. The Mutelist file uses the [YAML](https://en.wikipedia.org/wiki/YAML) format with the following syntax: ```yaml theme={null} ### Account, Check and/or Region can be * to apply for all the cases. ### Resources and tags are lists that can have either Regex or Keywords. ### Multiple tags in the list are "ANDed" together (ALL must match). ### Use regex alternation (|) within a single tag for "OR" logic (e.g., "env=dev|env=stg"). ### For each check you can use Exceptions to unmute specific Accounts, Regions, Resources and/or Tags. ### All conditions (Account, Check, Region, Resource, Tags) are ANDed together. ########################### MUTELIST EXAMPLE ########################### Mutelist: Accounts: "123456789012": Checks: "iam_user_hardware_mfa_enabled": Regions: - "us-east-1" Resources: - "user-1" # Will mute user-1 in check iam_user_hardware_mfa_enabled - "user-2" # Will mute user-2 in check iam_user_hardware_mfa_enabled Description: "Findings related with the check iam_user_hardware_mfa_enabled will be muted for us-east-1 region and user-1, user-2 resources" "ec2_*": Regions: - "*" Resources: - "*" # Will mute every EC2 check in every account and region "*": Regions: - "*" Resources: - "test" Tags: - "test=test" # Will mute every resource containing the string "test" and the tags 'test=test' and - "project=test|project=stage" # either of ('project=test' OR project=stage) in account 123456789012 and every region "*": Regions: - "*" Resources: - "test" Tags: - "test=test" - "project=test" # This will mute every resource containing the string "test" and BOTH tags at the same time. "*": Regions: - "*" Resources: - "test" Tags: # This will mute every resource containing the string "test" and the ones that contain EITHER the `test=test` OR `project=test` OR `project=dev` - "test=test|project=(test|dev)" "*": Regions: - "*" Resources: - "test" Tags: - "test=test" # This will mute every resource containing the string "test" and the tags `test=test` and either `project=test` OR `project=stage` in every account and region. - "project=test|project=stage" "*": Checks: "s3_bucket_object_versioning": Regions: - "eu-west-1" - "us-east-1" Resources: - "ci-logs" # Will mute bucket "ci-logs" AND ALSO bucket "ci-logs-replica" in specified check and regions - "logs" # Will mute EVERY BUCKET containing the string "logs" in specified check and regions - ".+-logs" # Will mute all buckets containing the terms ci-logs, qa-logs, etc. in specified check and regions "ecs_task_definitions_no_environment_secrets": Regions: - "*" Resources: - "*" Exceptions: Accounts: - "0123456789012" Regions: - "eu-west-1" - "eu-south-2" # Will mute every resource in check ecs_task_definitions_no_environment_secrets except the ones in account 0123456789012 located in eu-south-2 or eu-west-1 "*": Regions: - "*" Resources: - "*" Tags: - "environment=dev" # Will mute every resource containing the tag 'environment=dev' in every account and region "123456789012": Checks: "*": Regions: - "*" Resources: - "*" Exceptions: Resources: - "test" Tags: - "environment=prod" # Will mute every resource except in account 123456789012 except the ones containing the string "test" and tag environment=prod "*": Checks: "ec2_*": Regions: - "*" Resources: - "test-resource" # Will mute the resource "test-resource" in all accounts and regions for whatever check from the EC2 service ``` ### Account, Check, Region, Resource, and Tag | Field | Description | Logic | | - | - | - | | `account_id` | Use `*` to apply the mutelist to all accounts. Supports exact match or wildcard. | `AND` (with other fields) | | `check_name` | The name of the Prowler check. Use `*` to apply the mutelist to all checks, or `service_*` to apply it to all service's checks. Supports regex patterns. | `AND` (with other fields) | | `region` | The region identifier. Use `*` to apply the mutelist to all regions. Supports regex patterns. | `AND` (with other fields) | | `resource` | The resource identifier. Use `*` to apply the mutelist to all resources. Supports regex patterns. | `AND` (with other fields) | | `tags` | List of tag patterns in `key=value` format. **Multiple tags = AND** (all must match). **Regex alternation within single tag = OR** (use `tag1\|tag2`). | `AND` between tags, `OR` within regex | ### Description This field can be used to add information or some hints for the Mutelist rule. ## How to Use the Mutelist To use the Mutelist, you need to specify the path to the Mutelist YAML file using the `-w` or `--mutelist-file` option when running Prowler: ``` prowler -w mutelist.yaml ``` Replace `` with the appropriate provider name. ## Considerations * The Mutelist can be used in combination with other Prowler options, such as the `--service` or `--checks` option, to further customize the scanning process. * Make sure to review and update the Mutelist regularly to ensure it reflects the desired exclusions and remains up to date with your infrastructure. ## Current Limitations and Workarounds ### Limitation: No OR Logic Between Different Rule Sets The current Mutelist schema **does not support OR logic** between different condition sets. Each check can have only **one rule object**, and all conditions are **ANDed** together. **Example of unsupported scenario:** ```yaml theme={null} # ❌ INVALID: Cannot have multiple rule blocks for the same check Accounts: "*": Checks: "*": # Rule 1 Regions: ["eu-west-1", "us-west-2"] Resources: ["*"] "*": # Rule 2 - This will OVERWRITE Rule 1 (YAML duplicate key) Regions: ["us-east-1"] Tags: ["environment=dev"] ``` **Workaround: Use multiple scans with different mutelists** For complex scenarios requiring OR logic, run separate scans: ```bash theme={null} # Scan 1: Mute findings in non-critical regions prowler aws --mutelist-file mutelist_noncritical.yaml # Scan 2: Mute dev/stg in critical regions prowler aws --mutelist-file mutelist_critical.yaml --regions us-east-1,sa-east-1 ``` Then merge the outputs in your reporting pipeline. ### Limitation: Cannot Negate Regions You cannot express "all regions **except** X and Y". You must explicitly list all regions you want to mute. **Workaround:** ```yaml theme={null} # Must enumerate all unwanted regions Accounts: "*": Checks: "*": Regions: - "af-south-1" - "ap-east-1" # ... list all regions EXCEPT the ones you want to monitor Resources: ["*"] ``` ### Best Practices 1. **Use regex patterns for flexibility**: Instead of listing multiple resources, use regex patterns like `"dev-.*"` or `"test-instance-[0-9]+"` 2. **Combine tag OR logic with regex**: Use `"environment=dev|environment=stg|environment=test"` instead of multiple tag entries 3. **Be specific with exceptions**: Use the `Exceptions` field to unmute specific resources within a broader muting rule 4. **Test your mutelist**: Run Prowler with `--output-modes json` and verify that the expected findings are muted ## AWS Mutelist ### Muting Specific AWS Regions If you want to mute failed findings only in specific regions, create a file with the following syntax and run it with `prowler aws -w mutelist.yaml`: Mutelist: Accounts: "*": Checks: "*": Regions: * "ap-southeast-1" * "ap-southeast-2" Resources: * "\*" Description: "Description related with the muted findings for the check" ### Default Mutelist For the AWS Provider, Prowler is executed with a default AWS Mutelist with the AWS Resources that should be muted such as all resources created by AWS Control Tower when setting up a landing zone that can be found in [AWS Documentation](https://docs.aws.amazon.com/controltower/latest/userguide/shared-account-resources.html). You can see this Mutelist file in [`prowler/config/aws_mutelist.yaml`](https://github.com/prowler-cloud/prowler/blob/master/prowler/config/aws_mutelist.yaml). ### Supported Mutelist Locations The mutelisting flag supports the following AWS locations when using the AWS Provider: #### AWS S3 URI You will need to pass the S3 URI where your Mutelist YAML file was uploaded to your bucket: ``` prowler aws -w s3:////mutelist.yaml ``` > [!NOTE] > > Make sure that the used AWS credentials have `s3:GetObject` permissions in the S3 path where the mutelist file is located. #### AWS DynamoDB Table ARN You will need to pass the DynamoDB Mutelist Table ARN: ``` prowler aws -w arn:aws:dynamodb:::table/ ``` The DynamoDB Table must have the following String keys: ![](https://mintcdn.com/prowler/4_70Xe_kEssGaMJ6/images/cli/mutelist-keys.png?fit=max\&auto=format\&n=4_70Xe_kEssGaMJ6\&q=85\&s=da6f42bd0eedd9c72fc76a8f75e74134) The Mutelist Table must have the following columns: * Accounts (String): This field can contain either an Account ID or an `*` (which applies to all the accounts that use this table as a mutelist). * Checks (String): This field can contain either a Prowler Check Name or an `*` (which applies to all the scanned checks). * Regions (List): This field contains a list of regions where this mutelist rule is applied (it can also contain an `*` to apply all scanned regions). * Resources (List): This field contains a list of regular expressions (regex) that applies to the resources that are wanted to be muted. * Tags (List): -Optional- This field contains a list of tuples in the form of 'key=value' that applies to the resources tags that are wanted to be muted. * Exceptions (Map): -Optional- This field contains a map of lists of accounts/regions/resources/tags that are wanted to be excepted in the mutelist. The following example will mute all resources in all accounts for the EC2 checks in the regions `eu-west-1` and `us-east-1` with the tags `environment=dev` and `environment=prod`, except the resources containing the string `test` in the account `012345678912` and region `eu-west-1` with the tag `environment=prod`: ![](https://mintcdn.com/prowler/4_70Xe_kEssGaMJ6/images/cli/mutelist-row.png?fit=max\&auto=format\&n=4_70Xe_kEssGaMJ6\&q=85\&s=a37762acebfba48e21853e729a3fd98b) > [!NOTE] > > Make sure that the used AWS credentials have `dynamodb:PartiQLSelect` permissions in the table. #### AWS Lambda ARN You will need to pass the AWS Lambda Function ARN: ``` prowler aws -w arn:aws:lambda:REGION:ACCOUNT_ID:function:FUNCTION_NAME ``` Make sure that the credentials that Prowler uses can invoke the Lambda Function: ``` - PolicyName: GetMuteList PolicyDocument: Version: '2012-10-17' Statement: - Action: 'lambda:InvokeFunction' Effect: Allow Resource: arn:aws:lambda:REGION:ACCOUNT_ID:function:FUNCTION_NAME ``` The Lambda Function can then generate a Mutelist dynamically. Here is the code of an example Python Lambda Function that generates a Mutelist: ``` def handler(event, context): checks = {} checks["vpc_flow_logs_enabled"] = { "Regions": [ "*" ], "Resources": [ "" ], Optional("Tags"): [ "key:value" ] } al = { "Mutelist": { "Accounts": { "*": { "Checks": checks } } } } return al ``` # Parallel Execution Source: https://docs.prowler.com/user-guide/cli/tutorials/parallel-execution The strategy used here will be to execute Prowler once per service. You can modify this approach as per your requirements. This can help for really large accounts, but please be aware of AWS API rate limits: 1. **Service-Specific Limits**: Each AWS service has its own rate limits. For instance, Amazon EC2 might have different rate limits for launching instances versus making API calls to describe instances. 2. **API Rate Limits**: Most of the rate limits in AWS are applied at the API level. Each API call to an AWS service counts towards the rate limit for that service. 3. **Throttling Responses**: When you exceed the rate limit for a service, AWS responds with a throttling error. In AWS SDKs, these are typically represented as `ThrottlingException` or `RateLimitExceeded` errors. For information on Prowler's retrier configuration please refer to this [page](https://docs.prowler.com/user-guide/providers/aws/boto3-configuration/). > [!NOTE] > > You might need to increase the `--aws-retries-max-attempts` parameter from the default value of 3. The retrier follows an exponential backoff strategy. ## Linux Generate a list of services that Prowler supports, and populate this info into a file: ```bash theme={null} prowler aws --list-services | awk -F"- " '{print $2}' | sed '/^$/d' > services ``` Make any modifications for services you would like to skip scanning by modifying this file. Then create a new PowerShell script file `parallel-prowler.sh` and add the following contents. Update the `$profile` variable to the AWS CLI profile you want to run Prowler with. ```bash theme={null} #!/bin/bash # Change these variables as needed profile="your_profile" account_id=$(aws sts get-caller-identity --profile "${profile}" --query 'Account' --output text) echo "Executing in account: ${account_id}" # Maximum number of concurrent processes MAX_PROCESSES=5 # Loop through the services while read service; do echo "$(date '+%Y-%m-%d %H:%M:%S'): Starting job for service: ${service}" # Run the command in the background (prowler -p "$profile" -s "$service" -F "${account_id}-${service}" --only-logs; echo "$(date '+%Y-%m-%d %H:%M:%S') - ${service} has completed") & # Check if we have reached the maximum number of processes while [ $(jobs -r | wc -l) -ge ${MAX_PROCESSES} ]; do # Wait for a second before checking again sleep 1 done done < ./services # Wait for all background processes to finish wait echo "All jobs completed" ``` Output will be stored in the `output/` folder that is in the same directory from which you executed the script. ## Windows Generate a list of services that Prowler supports, and populate this info into a file: ```powershell theme={null} prowler aws --list-services | ForEach-Object { # Capture lines that are likely service names if ($_ -match '^\- \w+$') { $_.Trim().Substring(2) } } | Where-Object { # Filter out empty or null lines $_ -ne $null -and $_ -ne '' } | Set-Content -Path "services" ``` Make any modifications for services you would like to skip scanning by modifying this file. Then create a new PowerShell script file `parallel-prowler.ps1` and add the following contents. Update the `$profile` variable to the AWS CLI profile you want to run Prowler with. Change any parameters you would like when calling Prowler in the `Start-Job -ScriptBlock` section. Note that you need to keep the `--only-logs` parameter, else some encoding issue occurs when trying to render the progress-bar and Prowler won't successfully execute. ```powershell theme={null} $profile = "your_profile" $account_id = Invoke-Expression -Command "aws sts get-caller-identity --profile $profile --query 'Account' --output text" Write-Host "Executing Prowler in $account_id" # Maximum number of concurrent jobs $MAX_PROCESSES = 5 # Read services from a file $services = Get-Content -Path "services" # Array to keep track of started jobs $jobs = @() foreach ($service in $services) { # Start the command as a job $job = Start-Job -ScriptBlock { prowler -p ${using:profile} -s ${using:service} -F "${using:account_id}-${using:service}" --only-logs $endTimestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss" Write-Output "${endTimestamp} - $using:service has completed" } $jobs += $job Write-Host "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') - Starting job for service: $service" # Check if we have reached the maximum number of jobs while (($jobs | Where-Object { $_.State -eq 'Running' }).Count -ge $MAX_PROCESSES) { Start-Sleep -Seconds 1 # Check for any completed jobs and receive their output $completedJobs = $jobs | Where-Object { $_.State -eq 'Completed' } foreach ($completedJob in $completedJobs) { Receive-Job -Job $completedJob -Keep | ForEach-Object { Write-Host $_ } $jobs = $jobs | Where-Object { $_.Id -ne $completedJob.Id } Remove-Job -Job $completedJob } } } # Check for any remaining completed jobs $remainingCompletedJobs = $jobs | Where-Object { $_.State -eq 'Completed' } foreach ($remainingJob in $remainingCompletedJobs) { Receive-Job -Job $remainingJob -Keep | ForEach-Object { Write-Host $_ } Remove-Job -Job $remainingJob } Write-Host "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') - All jobs completed" ``` Output will be stored in `C:\Users\YOUR-USER\Documents\output\` ## Combining the Output Files Guidance is provided for the CSV file format. From the output directory, execute either the following Bash or PowerShell script. The script will collect the output from the CSV files, only include the header from the first file, and then output the result as CombinedCSV.csv in the current working directory. There is no logic implemented in terms of which CSV files it will combine. If you have additional CSV files from other actions, such as running a quick inventory, you will need to move that out of the current (or any nested) directory, or move the output you want to combine into its own folder and run the script from there. ```bash theme={null} #!/bin/bash # Initialize a variable to indicate the first file firstFile=true # Find all CSV files and loop through them find . -name "*.csv" -print0 | while IFS= read -r -d '' file; do if [ "$firstFile" = true ]; then # For the first file, keep the header cat "$file" > CombinedCSV.csv firstFile=false else # For subsequent files, skip the header tail -n +2 "$file" >> CombinedCSV.csv fi done ``` ```powershell theme={null} # Get all CSV files from current directory and its subdirectories $csvFiles = Get-ChildItem -Recurse -Filter "*.csv" # Initialize a variable to track if it's the first file $firstFile = $true # Loop through each CSV file foreach ($file in $csvFiles) { if ($firstFile) { # For the first file, keep the header and change the flag $combinedCsv = Import-Csv -Path $file.FullName $firstFile = $false } else { # For subsequent files, skip the header $tempCsv = Import-Csv -Path $file.FullName $combinedCsv += $tempCsv | Select-Object * -Skip 1 } } # Export the combined data to a new CSV file $combinedCsv | Export-Csv -Path "CombinedCSV.csv" -NoTypeInformation ``` ## TODO: Additional Improvements Some services need to instantiate another service to perform a check. For instance, `cloudwatch` will instantiate Prowler's `iam` service to perform the `cloudwatch_cross_account_sharing_disabled` check. When the `iam` service is instantiated, it will perform the `__init__` function, and pull all the information required for that service. This provides an opportunity for an improvement in the above script to group related services together so that the `iam` services (or any other cross-service references) aren't repeatedly instantiated by grouping dependent services together. A complete mapping between these services still needs to be further investigated, but these are the cross-references that have been noted: * inspector2 needs lambda and ec2 * cloudwatch needs iam * dlm needs ec2 # Pentesting Source: https://docs.prowler.com/user-guide/cli/tutorials/pentesting Prowler has some checks that analyse pentesting risks (Secrets, Internet Exposed, AuthN, AuthZ, and more). ## Detect Secrets Prowler scans for secrets stored in plaintext within the audited environment using [Kingfisher](https://github.com/mongodb/kingfisher), an open-source secret-scanning engine. By default these scans run fully offline, so no data leaves the audited environment. Discovered secrets can optionally be validated against the provider APIs to confirm whether they are live — see [Validating Discovered Secrets](/user-guide/cli/tutorials/configuration_file#validating-discovered-secrets). The checks with this functionality are the following. AWS: * apigateway\_restapi\_no\_secrets\_in\_stage\_variables * autoscaling\_find\_secrets\_ec2\_launch\_configuration * awslambda\_function\_no\_secrets\_in\_code * awslambda\_function\_no\_secrets\_in\_variables * cloudformation\_stack\_outputs\_find\_secrets * cloudwatch\_log\_group\_no\_secrets\_in\_logs * codebuild\_project\_no\_secrets\_in\_variables * ec2\_instance\_secrets\_user\_data * ec2\_launch\_template\_no\_secrets * ecs\_task\_definitions\_no\_environment\_secrets * glue\_etl\_jobs\_no\_secrets\_in\_arguments * ssm\_document\_secrets * stepfunctions\_statemachine\_no\_secrets\_in\_definition OpenStack: * compute\_instance\_metadata\_sensitive\_data * blockstorage\_volume\_metadata\_sensitive\_data * blockstorage\_snapshot\_metadata\_sensitive\_data * objectstorage\_container\_metadata\_sensitive\_data To execute the secret-scanning checks, run the following command: ```console theme={null} prowler --categories secrets ``` ## Internet Exposed Resources Several checks analyse resources that are exposed to the Internet, these are: * apigateway\_restapi\_public * appstream\_fleet\_default\_internet\_access\_disabled * awslambda\_function\_not\_publicly\_accessible * ec2\_ami\_public * ec2\_ebs\_public\_snapshot * ec2\_instance\_internet\_facing\_with\_instance\_profile * ec2\_instance\_port\_X\_exposed\_to\_internet (where X is the port number) * ec2\_instance\_public\_ip * ec2\_networkacl\_allow\_ingress\_any\_port * ec2\_securitygroup\_allow\_wide\_open\_public\_ipv4 * ec2\_securitygroup\_allow\_ingress\_from\_internet\_to\_any\_port * ecr\_repositories\_not\_publicly\_accessible * eks\_control\_plane\_endpoint\_access\_restricted * eks\_endpoints\_not\_publicly\_accessible * elbv2\_internet\_facing * kms\_key\_not\_publicly\_accessible * opensearch\_service\_domains\_not\_publicly\_accessible * rds\_instance\_no\_public\_access * rds\_snapshots\_public\_access * s3\_bucket\_policy\_public\_write\_access * s3\_bucket\_public\_access * sagemaker\_notebook\_instance\_without\_direct\_internet\_access\_configured * sns\_topics\_not\_publicly\_accessible * sqs\_queues\_not\_publicly\_accessible * network\_public\_ip\_shodan To execute Internet-exposed related checks, you can run the following command: ```console theme={null} prowler --categories internet-exposed ``` ### Shodan Prowler can check whether any public IPs in cloud environments are exposed in Shodan using the `-N`/`--shodan` option. #### Using the Environment Variable (Recommended) Set the `SHODAN_API_KEY` environment variable to avoid exposing the API key in process listings and shell history: ```console theme={null} export SHODAN_API_KEY= ``` Then run Prowler with the `--shodan` flag (no value needed): ```console theme={null} prowler aws --shodan -c ec2_elastic_ip_shodan ``` ```console theme={null} prowler azure --shodan -c network_public_ip_shodan ``` ```console theme={null} prowler gcp --shodan -c compute_public_address_shodan ``` #### Using the CLI Flag Alternatively, pass the API key directly on the command line: ```console theme={null} prowler aws --shodan -c ec2_elastic_ip_shodan ``` > [!WARNING] > > Passing secret values directly on the command line exposes them in process listings and shell history. Prowler CLI displays a warning when this pattern is detected. Use the `SHODAN_API_KEY` environment variable instead. # Quick Inventory Source: https://docs.prowler.com/user-guide/cli/tutorials/quick-inventory Prowler allows you to execute a quick inventory to extract the number of resources in your provider. > [!NOTE] > > Currently, it is only available for AWS provider. * You can use option `-i`/`--quick-inventory` to execute it: ```sh theme={null} prowler -i ``` > [!NOTE] > > By default, it extracts resources from all the regions, you could use `-f`/`--filter-region` to specify the regions to execute the analysis. * This feature specifies both the number of resources for each service and for each resource type. * Also, it creates by default a CSV and JSON to see detailed information about the resources extracted. ![Quick Inventory Example](https://mintcdn.com/prowler/9AoCN7Q_gXN7wF7l/images/quick-inventory.jpg?fit=max\&auto=format\&n=9AoCN7Q_gXN7wF7l\&q=85\&s=15379e9c4b52c188662ab85c8922c53d) ## Objections The inventorying process is carried out with `resourcegroupstaggingapi` calls, which means that only resources they have or have had tags will appear (except for the IAM and S3 resources which are done with Boto3 API calls). # Reporting in Prowler Source: https://docs.prowler.com/user-guide/cli/tutorials/reporting Prowler generates security assessment reports in multiple formats, ensuring compatibility with various analysis tools and AWS integrations. ## Default Report Generation By default, Prowler outputs reports in CSV and JSON-[OCSF](https://schema.ocsf.io/) formats: ```console theme={null} prowler -M csv json-ocsf json-asff html ``` If you require reports in JSON-ASFF (used by AWS Security Hub), set it using the `-M/--output-modes/--output-formats` flag, as in the following example: ```console theme={null} prowler --output-formats json-asff ``` ## Compliance Reports All compliance-related reports are automatically generated when Prowler is executed. These outputs are stored in the `/output/compliance` directory. ## Custom Output Flags By default, Prowler creates a file inside the `output` directory named: `prowler-output-ACCOUNT_NUM-OUTPUT_DATE.format`. However, both the output file name and directory can be personalised: * Custom output report name: You can use the flag `-F`/`--output-filename` ```console theme={null} prowler -M csv json-ocsf json-asff -F ``` * Custom output directory: You can use the flag `-o`/`--output-directory` ```console theme={null} prowler -M csv json-ocsf json-asff -o ``` > [!NOTE] > > Both flags can be used simultaneously to provide a custom directory and filename. `console prowler -M csv json-ocsf json-asff \ -F -o ` ## Output Timestamp Format By default, the timestamp format of the output files is ISO 8601. This can be changed with the flag `--unix-timestamp` generating the timestamp fields in pure unix timestamp format. ## Supported Output Formats Prowler natively supports the following reporting output formats: * CSV * JSON-OCSF * JSON-ASFF (AWS only) * HTML * SARIF (IaC only) Hereunder is the structure for each of the supported report formats by Prowler: ### CSV The CSV format follows a standardized structure across all providers. The following are the available columns: * AUTH\_METHOD * TIMESTAMP * ACCOUNT\_UID * ACCOUNT\_NAME * ACCOUNT\_EMAIL * ACCOUNT\_ORGANIZATION\_UID * ACCOUNT\_ORGANIZATION\_NAME * ACCOUNT\_TAGS * FINDING\_UID * PROVIDER * CHECK\_ID * CHECK\_TITLE * CHECK\_TYPE * STATUS * STATUS\_EXTENDED * MUTED * SERVICE\_NAME * SUBSERVICE\_NAME * SEVERITY * RESOURCE\_TYPE * RESOURCE\_UID * RESOURCE\_NAME * RESOURCE\_DETAILS * RESOURCE\_TAGS * PARTITION * REGION * DESCRIPTION * RISK * RELATED\_URL * REMEDIATION\_RECOMMENDATION\_TEXT * REMEDIATION\_RECOMMENDATION\_URL * REMEDIATION\_CODE\_NATIVEIAC * REMEDIATION\_CODE\_TERRAFORM * REMEDIATION\_CODE\_CLI * REMEDIATION\_CODE\_OTHER * COMPLIANCE * CATEGORIES * DEPENDS\_ON * RELATED\_TO * NOTES * PROWLER\_VERSION * ADDITIONAL\_URLS #### CSV Headers Mapping The following table shows the mapping between the CSV headers and the providers fields: | Open Source Consolidated | AWS | GCP | AZURE | KUBERNETES | | - | - | - | - | - | | auth\_method | profile | principal | identity\_type : identity\_id | in-cluster/kube-config | | provider | provider | provider | provider | provider | | account\_uid | account\_id / account\_arn | project\_id | subscription\_id | cluster | | account\_name | account\_name | project\_name | subscription\_name | context:context | | account\_email | account\_email | N/A | N/A | N/A | | account\_organization\_uid | account\_organizations\_arn | project\_organization\_id | tenant\_id | N/A | | account\_organization\_name | account\_org | project\_organization\_display\_name | tenant\_domain | N/A | | account\_tags | account\_tags | project\_labels | subscription\_tags | N/A | | partition | partition | N/A | region\_config.name | N/A | | region | region | location | location | namespace:namespace | | resource\_name | resource\_id | resource\_name | resource\_name | resource\_name | | resource\_uid | resource\_arn | resource\_id | resource\_id | resource\_id | | finding\_uid | finding\_unique\_id | finding\_unique\_id | finding\_unique\_id | finding\_unique\_id | ### JSON-OCSF The JSON-OCSF output format implements the [Detection Finding](https://schema.ocsf.io/classes/detection_finding) from the [OCSF](https://schema.ocsf.io) ```json theme={null} [{ "message": "Potential secrets found in ECS task definition manufacturer-api with revision 7: Secrets in container manufacturer-api -> Secret Keyword on the environment variable DB_PASSWORD.", "metadata": { "event_code": "ecs_task_definitions_no_environment_secrets", "product": { "name": "Prowler", "uid": "prowler", "vendor_name": "Prowler", "version": "5.3.0" }, "profiles": [ "cloud", "datetime" ], "tenant_uid": "", "version": "1.3.0" }, "severity_id": 5, "severity": "Critical", "status": "New", "status_code": "FAIL", "status_detail": "Potential secrets found in ECS task definition manufacturer-api with revision 7: Secrets in container manufacturer-api -> Secret Keyword on the environment variable DB_PASSWORD.", "status_id": 1, "unmapped": { "related_url": "", "categories": [ "secrets" ], "depends_on": [], "related_to": [], "notes": "", "additional_urls": [], "compliance": { "MITRE-ATTACK": [ "T1552" ], "AWS-Foundational-Security-Best-Practices": [ "ecs" ], "KISA-ISMS-P-2023": [ "2.7.1", "2.11.2" ], "KISA-ISMS-P-2023-korean": [ "2.7.1", "2.11.2" ], "AWS-Well-Architected-Framework-Security-Pillar": [ "SEC02-BP03" ] } }, "activity_name": "Create", "activity_id": 1, "finding_info": { "created_time": 1737995806, "created_time_dt": "2025-01-27T17:36:46.855898", "desc": "Check if secrets exists in ECS task definitions environment variables.", "product_uid": "prowler", "title": "Check if secrets exists in ECS task definitions environment variables", "types": [ "Protect", "Secure development", "Credentials not hard-coded" ], "uid": "prowler-aws-ecs_task_definitions_no_environment_secrets-123456789012-eu-central-1-manufacturer-api:7" }, "resources": [ { "cloud_partition": "aws", "region": "eu-central-1", "data": { "details": "", "metadata": { "name": "manufacturer-api", "arn": "arn:aws:ecs:eu-central-1:123456789012:task-definition/manufacturer-api:7", "revision": "7", "region": "eu-central-1", "container_definitions": [ { "name": "manufacturer-api", "privileged": false, "readonly_rootfilesystem": false, "user": "", "environment": [ { "name": "DB_HOST", "value": "some.cluster.eu-central-1.rds.amazonaws.com" }, { "name": "DB_PASSWORD", "value": "somePassword" } ], "log_driver": "", "log_option": "" } ], "pid_mode": "", "tags": [], "network_mode": "awsvpc" } }, "group": { "name": "ecs" }, "labels": [], "name": "manufacturer-api:7", "type": "AwsEcsTaskDefinition", "uid": "arn:aws:ecs:eu-central-1:123456789012:task-definition/manufacturer-api:7" } ], "category_name": "Findings", "category_uid": 2, "class_name": "Detection Finding", "class_uid": 2004, "cloud": { "account": { "name": "", "type": "AWS Account", "type_id": 10, "uid": "123456789012", "labels": [] }, "org": { "name": "", "uid": "" }, "provider": "aws", "region": "eu-central-1" }, "remediation": { "desc": "Use Secrets Manager or Parameter Store to securely provide credentials to containers without hardcoding the secrets in code or passing them through environment variables. It is currently not possible to delete task definition revisions which contain plaintext secrets. AWS is looking into implementing this feature in 2023, and it is therefore recommended that all plaintext secrets are rotated at the same time as moving the secrets to Secrets Manager or Parameter Store.", "references": [ "https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html" ] }, "risk_details": "The use of a hard-coded password increases the possibility of password guessing. If hard-coded passwords are used, it is possible that malicious users gain access through the account in question.", "time": 1737995806, "time_dt": "2025-01-27T17:36:46.855898", "type_uid": 200401, "type_name": "Detection Finding: Create" }] ``` > [!NOTE] > > Each finding is a `json` object within a list. ### JSON-ASFF (AWS Only) > [!NOTE] > > Only available when using `--security-hub` or `--output-formats json-asff` with the AWS provider. The following code is an example output of the [JSON-ASFF](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format-syntax.html) format: ```json theme={null} [{ "SchemaVersion": "2018-10-08", "Id": "prowler-rds_instance_minor_version_upgrade_enabled-ACCOUNT_ID-eu-west-1-b1ade474a", "ProductArn": "arn:aws:securityhub:eu-west-1::product/prowler/prowler", "RecordState": "ACTIVE", "ProductFields": { "ProviderName": "Prowler", "ProviderVersion": "3.0-beta-21Nov2022", "ProwlerResourceName": "rds-instance-id" }, "GeneratorId": "prowler-rds_instance_minor_version_upgrade_enabled", "AwsAccountId": "ACCOUNT_ID", "Types": [], "FirstObservedAt": "2022-12-01T13:16:57Z", "UpdatedAt": "2022-12-01T13:16:57Z", "CreatedAt": "2022-12-01T13:16:57Z", "Severity": { "Label": "LOW" }, "Title": "Ensure RDS instances have minor version upgrade enabled.", "Description": "Ensure RDS instances have minor version upgrade enabled.", "Resources": [ { "Type": "AwsRdsDbInstance", "Id": "rds-instance-id", "Partition": "aws", "Region": "eu-west-1" } ], "Compliance": { "Status": "PASSED", "RelatedRequirements": [ "CISA your-systems-2 booting-up-thing-to-do-first-3", "CIS-1.5 2.3.2", "AWS-Foundational-Security-Best-Practices rds", "RBI-Cyber-Security-Framework annex_i_6", "FFIEC d3-cc-pm-b-1 d3-cc-pm-b-3" ], "AssociatedStandards": [ { "StandardsId": "CISA" }, { "StandardsId": "CIS-1.5" }, { "StandardsId": "AWS-Foundational-Security-Best-Practices" }, { "StandardsId": "RBI-Cyber-Security-Framework" }, { "StandardsId": "FFIEC" } ] }, "Remediation": { "Recommendation": { "Text": "Enable auto minor version upgrade for all databases and environments.", "Url": "https://aws.amazon.com/blogs/database/best-practices-for-upgrading-amazon-rds-to-major-and-minor-versions-of-postgresql/" } } }] ``` > [!NOTE] > > Each finding is a `json` object within a list. ### HTML The following image is an example of the HTML output: ![](https://mintcdn.com/prowler/4_70Xe_kEssGaMJ6/images/cli/reporting/html-output.png?fit=max\&auto=format\&n=4_70Xe_kEssGaMJ6\&q=85\&s=dd8199c2870e7b95f779d59e12245142) ### SARIF (IaC Only) [Added in:  5.25.0](https://github.com/prowler-cloud/prowler/releases/tag/5.25.0) The SARIF (Static Analysis Results Interchange Format) output generates a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) document compatible with GitHub Code Scanning and other SARIF-compatible tools. This format is exclusively available for the IaC provider, as it is designed for static analysis results that reference specific files and line numbers. ```console theme={null} prowler iac --scan-repository-url https://github.com/user/repo -M sarif ``` > [!NOTE] > > The SARIF output format is only available when using the `iac` provider. Attempting to use it with other providers results in an error. The SARIF output includes: * **Rules:** Each unique check ID produces a rule entry with severity, description, remediation, and a markdown help panel. * **Results:** Only failed (non-muted) findings are included, with file paths and line numbers for precise annotation. * **Severity mapping:** Prowler severities map to SARIF levels (`critical`/`high` → `error`, `medium` → `warning`, `low`/`informational` → `note`). ## V4 Deprecations Some deprecations have been made to unify formats and improve outputs. ### JSON Native JSON format has been deprecated in favor of JSON [OCSF](https://schema.ocsf.io/) `v1.1.0`. The following is the mapping between the native JSON and the Detection Finding from the JSON-OCSF: | Native JSON Prowler v3 | JSON-OCSF v.1.1.0 | | - | - | | AssessmentStartTime | time\_dt | | FindingUniqueId | finding\_info.uid | | Provider | cloud.provider | | CheckID | metadata.event\_code | | CheckTitle | finding\_info.title | | CheckType | finding\_info.types | | ServiceName | resources.group.name | | SubServiceName | *Not mapped yet* | | Status | status\_code | | StatusExtended | status\_detail | | Severity | severity | | ResourceType | resources.type | | ResourceDetails | resources.data.details | | Description | finding\_info.desc | | Risk | risk\_details | | RelatedUrl | unmapped.related\_url | | Remediation.Recommendation.Text | remediation.desc | | Remediation.Recommendation.Url | remediation.references | | Remediation.Code.NativeIaC | remediation.references | | Remediation.Code.Terraform | remediation.references | | Remediation.Code.CLI | remediation.references | | Remediation.Code.Other | remediation.references | | Compliance | unmapped.compliance | | Categories | unmapped.categories | | DependsOn | unmapped.depends\_on | | RelatedTo | unmapped.related\_to | | AdditionalURLs | unmapped.additional\_urls | | Notes | unmapped.notes | | Profile | *Not mapped yet* | | AccountId | cloud.account.uid | | OrganizationsInfo.account\_name | cloud.account.name | | OrganizationsInfo.account\_email | *Not mapped yet* | | OrganizationsInfo.account\_arn | *Not mapped yet* | | OrganizationsInfo.account\_org | cloud.org.name | | OrganizationsInfo.account\_tags | cloud.account.labels | | Region | resources.region | | ResourceId | resources.name | | ResourceArn | resources.uid | | ResourceTags | resources.labels | ### CSV Columns In Prowler v3 each provider had some specific columns, different from the rest. These are the cases that have changed in Prowler v4: | Provider | v3 | v4 | | - | - | - | | AWS | PROFILE | AUTH\_METHOD | | AWS | ACCOUNT\_ID | ACCOUNT\_UID | | AWS | ACCOUNT\_ORGANIZATION\_ARN | ACCOUNT\_ORGANIZATION\_UID | | AWS | ACCOUNT\_ORG | ACCOUNT\_ORGANIZATION\_NAME | | AWS | FINDING\_UNIQUE\_ID | FINDING\_UID | | AWS | ASSESSMENT\_START\_TIME | TIMESTAMP | | AZURE | TENANT\_DOMAIN | ACCOUNT\_ORGANIZATION\_NAME | | AZURE | SUBSCRIPTION | ACCOUNT\_UID | | GCP | PROJECT\_ID | ACCOUNT\_UID | | GCP | LOCATION | REGION | | AWS / AZURE / GCP | RESOURCE\_ID | RESOURCE\_NAME | | AWS / AZURE / GCP | RESOURCE\_ARN | RESOURCE\_UID | # Scanning Unused Services Source: https://docs.prowler.com/user-guide/cli/tutorials/scan-unused-services > [!NOTE] > > This feature is currently available only for the AWS provider. By default, Prowler scans only actively used cloud services (services with resources deployed). This reduces unnecessary findings in reports. To include unused services in the scan, use the following command: ```console theme={null} prowler --scan-unused-services ``` ## Services Ignored ### AWS #### ACM (AWS Certificate Manager) Certificates stored in ACM without active usage in AWS resources are excluded. By default, Prowler only scans actively used certificates. Unused certificates are not evaluated for expiration, transparency logging, or weak key algorithms. * `acm_certificates_expiration_check` * `acm_certificates_transparency_logs_enabled` * `acm_certificates_with_secure_key_algorithms` #### Athena Upon AWS account creation, Athena provisions a default primary workgroup for the user. Prowler verifies if this workgroup is enabled and used by checking for queries within the last 45 days. If Athena is unused, findings related to its checks will not appear. * `athena_workgroup_encryption` * `athena_workgroup_enforce_configuration` * `athena_workgroup_logging_enabled` #### Amazon Bedrock Generative AI workloads benefit from private VPC endpoint connectivity to keep prompt and model traffic off the public internet. Prowler only evaluates this configuration for VPCs in use (with active ENIs). * `bedrock_vpc_endpoints_configured` #### AWS CloudTrail AWS CloudTrail should have at least one trail with a data event to record all S3 object-level API operations. Before flagging this issue, Prowler verifies if S3 buckets exist in the account. * `cloudtrail_s3_dataevents_read_enabled` * `cloudtrail_s3_dataevents_write_enabled` #### AWS Elastic Compute Cloud (EC2) If Amazon Elastic Block Store (EBS) default encryption is not enabled, sensitive data at rest remains unprotected in EC2. Prowler only generates a finding if EBS volumes exist where default encryption could be enforced. * `ec2_ebs_default_encryption` **EBS Snapshot Public Access**: Public EBS snapshots can leak data. Prowler only evaluates the account-level block setting if EBS snapshots exist in the account. * `ec2_ebs_snapshot_account_block_public_access` **EC2 Instance Metadata Service (IMDS)**: Enforcing IMDSv2 at the account level mitigates SSRF-based credential theft. Prowler only evaluates the account-level setting if EC2 instances exist in the account. * `ec2_instance_account_imdsv2_enabled` **Security Groups**: Misconfigured security groups increase the attack surface. Prowler scans only attached security groups to report vulnerabilities in actively used configurations. Applies to: * 20 security group-related checks, including open ports and ingress/egress traffic rules. * `ec2_securitygroup_allow_ingress_from_internet_to_port_X` * `ec2_securitygroup_default_restrict_traffic` * `ec2_securitygroup_allow_wide_open_public_ipv4` * 3 network ACL-related checks, ensuring only active ACLs with open ports are flagged. * `ec2_networkacl_allow_ingress_X_port` #### AWS Identity and Access Management (IAM) Customer-managed IAM policies that are not attached to any user, group, or role grant no effective permissions until a principal is bound to them. Prowler treats such policies as dormant by default and skips the content-evaluation checks below when `--scan-unused-services` is not set. Enable the flag to surface findings on unattached policies as well. * `iam_policy_allows_privilege_escalation` * `iam_policy_no_full_access_to_cloudtrail` * `iam_policy_no_full_access_to_kms` * `iam_policy_no_wildcard_marketplace_subscribe` * `iam_no_custom_policy_permissive_role_assumption` The dedicated `iam_customer_unattached_policy_no_administrative_privileges` check still inspects unattached policies regardless of the flag, since its purpose is to highlight dormant administrator privileges. #### AWS Glue AWS Glue best practices recommend encrypting metadata and connection passwords in Data Catalogs. Prowler verifies service usage by checking for existing Data Catalog tables before applying findings. * `glue_data_catalogs_connection_passwords_encryption_enabled` * `glue_data_catalogs_metadata_encryption_enabled` #### Amazon Inspector Amazon Inspector is a vulnerability discovery service that automates continuous security scans for Amazon EC2, Amazon ECR, and AWS Lambda environments. Prowler recommends enabling Amazon Inspector and addressing all findings. By default, Prowler only triggers alerts if there are Lambda functions, EC2 instances, or ECR repositories in the region where Amazon Inspector should be enabled. * `inspector2_is_enabled` #### AWS Key Management Service (KMS) Customer managed Customer Master Keys (CMKs) in the `Disabled` state cannot be used for cryptographic operations, so Prowler skips the unintentional-deletion check on them by default. Enable the flag to evaluate disabled CMKs as well. * `kms_cmk_not_deleted_unintentionally` #### Amazon Macie Amazon Macie leverages machine learning to automatically discover, classify, and protect sensitive data in S3 buckets. Prowler only generates findings if Macie is disabled and there are S3 buckets in the AWS account. * `macie_is_enabled` #### Network Firewall A network firewall is essential for monitoring and controlling traffic within a Virtual Private Cloud (VPC). Prowler only alerts for VPCs in use, specifically those containing ENIs (Elastic Network Interfaces). * `networkfirewall_in_all_vpc` #### Amazon Relational Database Service (RDS) RDS event subscriptions notify operators of critical database events. Prowler only evaluates these subscription checks when RDS clusters or instances exist in the account. * `rds_cluster_critical_event_subscription` * `rds_instance_critical_event_subscription` * `rds_instance_event_subscription_parameter_groups` * `rds_instance_event_subscription_security_groups` #### Amazon S3 To prevent unintended data exposure: Public Access Block should be enabled at the account level. Prowler only checks this setting if S3 buckets exist in the account. * `s3_account_level_public_access_blocks` #### Virtual Private Cloud (VPC) VPC settings directly impact network security and availability. * VPC Flow Logs: Provide visibility into network traffic for security monitoring. Prowler only checks if Flow Logs are enabled for VPCs in use, i.e., those with active ENIs. * `vpc_flow_logs_enabled` * VPC Endpoint for EC2: Routes EC2 API calls through a private VPC endpoint to keep traffic off the public internet. Prowler only evaluates this configuration for VPCs in use, i.e., those with active ENIs. * `vpc_endpoint_for_ec2_enabled` * VPC Subnet Public IP Restrictions: Prevent unintended exposure of resources to the internet. Prowler only checks this configuration for VPCs in use, i.e., those with active ENIs. * `vpc_subnet_no_public_ip_by_default` * Separate Private and Public Subnets: Best practice to avoid exposure risks. Prowler only checks this configuration for VPCs in use, i.e., those with active ENIs. * `vpc_subnet_separate_private_public` * Multi-AZ Subnet Distribution: VPCs should have subnets in different availability zones to prevent a single point of failure. Prowler only checks this configuration for VPCs in use, i.e., those with active ENIs. * `vpc_subnet_different_az` # Compliance Source: https://docs.prowler.com/user-guide/compliance/tutorials/compliance Run security checks against compliance frameworks, review posture across providers, use Compliance Watchlist to pin frameworks, and download CSV or PDF reports from Prowler Cloud, or CSV reports from Prowler CLI. Prowler maps every security check to one or more industry-standard compliance frameworks, so a single scan produces both technical findings and framework-aligned evidence. The same evaluation runs identically whether scans are launched from Prowler Cloud, Prowler Local Server, or Prowler CLI. Out of the box, Prowler covers frameworks such as CIS Benchmarks, NIST 800-53, NIST CSF, NIS2, ENS RD2022, ISO 27001, PCI-DSS, SOC 2, GDPR, HIPAA, AWS Well-Architected, BSI C5, CSA CCM, MITRE ATT\&CK, KISA ISMS-P, FedRAMP, and Prowler ThreatScore. The full catalog is available at [Prowler Hub](https://hub.prowler.com/compliance). > [!NOTE] > > For the unified compliance score methodology used across frameworks, see [Prowler ThreatScore](/user-guide/compliance/tutorials/threatscore). > [card] [Prowler Cloud](#prowler-cloud) > > Review compliance posture using Prowler Cloud > [card] [Prowler CLI](#prowler-cli) > > Run compliance scans using Prowler CLI ## Prowler Cloud The Compliance section in Prowler Cloud centralizes compliance posture across every connected provider. It aggregates scan results, surfaces Prowler ThreatScore, and exposes detailed requirement-level evidence for each supported framework. ### Accessing the Compliance Section To open the compliance overview, follow these steps: 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in). 2. Select **Compliance** from the left navigation. The Compliance page is organized into two tabs: * **Single Scan:** Lists every framework evaluated by one completed scan of one provider. This is the experience described in the rest of this guide, and the default view in Prowler Local Server. * **Multiple Scans:** Aggregates one framework across several scans at once, either across provider types ([Cross-Provider Type Compliance](/user-guide/compliance/tutorials/cross-provider-type-compliance)) or across every provider of the same type ([Cross-Provider Compliance](/user-guide/compliance/tutorials/cross-provider-compliance)). > [!NOTE] > > This Multiple Scans tab is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). ![Compliance overview page in Prowler Cloud showing filters, the Prowler ThreatScore card, and the framework grid](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-overview.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=f26a8e9d87f6c2fd3ce01123b136ded0) > [!NOTE] > > Compliance results require at least one completed scan. If no scan has finished yet, Prowler Cloud displays a notice prompting to launch or wait for a scan to complete. ### Filtering Compliance Results The filters bar at the top of the overview controls which scan and which regions feed every card on the page. #### Scan Selector The scan selector lists completed scans across all connected providers. Each entry includes the provider type, alias, and completion timestamp. Selecting a scan updates the entire page, including ThreatScore and every framework card. #### Region Filter The region multi-select narrows results to one or more regions detected in the selected scan. Use it to evaluate compliance posture for a specific geography or regulatory boundary. The filter applies to: * The framework grid scores and pass/fail counts. * The detailed requirement view inside each framework. > [!NOTE] > > Region filters apply only to providers that report a region attribute (for example, AWS, Azure, and Google Cloud). Providers without regions ignore the filter. #### Clearing Filters Select **Clear filters** to reset both the region filter and any other applied filter to its default state. The scan selector is preserved. ### Reviewing the Prowler ThreatScore Card When the selected scan includes Prowler ThreatScore data, a dedicated card appears at the top of the overview, showing: * The overall ThreatScore (0–100) with a color-coded indicator. * A progress bar reflecting current posture. * Per-pillar bars for IAM, Attack Surface, and Logging and Monitoring. ![Prowler ThreatScore badge on the Compliance overview showing the overall score and per-pillar bars](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-threatscore-card.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=2c5616f54cd05fa8815ef9c74da47d1c) Selecting the card opens the ThreatScore framework detail page, covered in [Working With the Framework Detail Page](#working-with-the-framework-detail-page). For a complete explanation of the methodology, formula, and weighting, see [Prowler ThreatScore](/user-guide/compliance/tutorials/threatscore). ### Exploring the Framework Grid Below ThreatScore, the framework grid shows one card per supported compliance framework. Each card includes: * **Framework logo and name:** Identifies the standard (CIS, NIST, ENS, ISO 27001, PCI-DSS, SOC 2, NIS2, CSA CCM, MITRE ATT\&CK, and more). * **Version:** Indicates the framework version applied to the scan. * **Score:** The percentage of passing requirements over the total evaluated. * **Passing Requirements:** A `passed / total` counter for additional context. * **Download dropdown:** Quick access to the CSV report and, when supported, the PDF report. ![Download dropdown on a framework card showing CSV and PDF report options](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-card-download.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=91e2a3b0b0aa664ae8e7e5b78fb18b56) Select any card to open the framework detail page. > [!NOTE] > > Score color coding follows three thresholds: red for severely low compliance, amber for partial compliance, and green for healthy posture. Hover over the score for the exact percentage. ### Tracking Frameworks With the Compliance Watchlist [Added in:  5.38.0](https://github.com/prowler-cloud/prowler/releases/tag/5.38.0) > [!NOTE] > > This Compliance Watchlist is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). The compliance catalog lists dozens of frameworks, while an organization usually tracks a handful. In Prowler Cloud, Compliance Watchlist keeps that handful in front: pin the frameworks that matter and narrow every compliance surface down to them. The watchlist is shared by the whole organization: one list per tenant, not a per-user bookmark, so every member sees the same pinned frameworks. #### Pinning a Framework Every framework card carries a pin button in its top-right corner. Select the pin to add the framework to the watchlist, and select it again to remove it. Pinning is available on the three compliance surfaces: * **Single Scan:** The framework grid of the selected scan. * **Across provider types:** The universal framework cards in the **Multiple Scans** tab. * **Across providers:** The framework cards inside each provider type group in the **Multiple Scans** tab. ![Single Scan framework grid where every card carries a pin button, with the pinned frameworks showing a filled pin](https://mintcdn.com/prowler/hxdg66D95nJJyk4c/images/compliance/prowler-app-compliance-single-scan-pins.png?fit=max\&auto=format\&n=hxdg66D95nJJyk4c\&q=85\&s=50d55fbd094f28c546e5396bace1a73a) > [!NOTE] > > Universal frameworks (CSA CCM, CIS Controls, DORA) are a single watchlist entry. Pinning one of them from any surface shows it as pinned on the others. #### Filtering With the Watchlist Two controls sit above the tabs, because both tabs read the same watchlist: * **Show only watchlist:** A toggle that hides every framework not in the watchlist, on both tabs at once. When the filter leaves a section with nothing to show, the section explains that no pinned framework matches and offers to clear the filter. * **Watchlist selector:** A searchable multi-select over the full framework catalog, grouped by provider. Use it to pin or unpin several frameworks in one place instead of visiting each card. ![Watchlist selector open above the compliance tabs, showing the searchable framework catalog grouped by provider with the pinned frameworks selected](https://mintcdn.com/prowler/hxdg66D95nJJyk4c/images/compliance/prowler-app-compliance-watchlist-editor.png?fit=max\&auto=format\&n=hxdg66D95nJJyk4c\&q=85\&s=35c5da10879ca3735bd5e7ba792dda38) In Prowler Cloud, the compliance framework chips in the finding details panel follow the watchlist as well, so triage points to the same frameworks the organization tracks. #### Reviewing the Watchlist on the Overview Page The **Compliance Watchlist** card on the Overview page lists exactly the pinned frameworks with their current score, computed from the latest completed scan per provider. Selecting an entry opens the framework detail page. Until a framework is pinned, the card is empty and prompts to start pinning from the Compliance section. ![Compliance Watchlist card on the Overview page listing the six pinned frameworks with their scores](https://mintcdn.com/prowler/hxdg66D95nJJyk4c/images/compliance/prowler-app-overview-compliance-watchlist.png?fit=max\&auto=format\&n=hxdg66D95nJJyk4c\&q=85\&s=95c1cd1b07063537c356244b4a79403b) > [!NOTE] > > In Prowler Local Server, where the watchlist is not available, the card keeps its previous behavior and ranks every framework with scan data. ### Working With the Framework Detail Page The detail page provides everything needed to evaluate a single framework: aggregate metrics, top failure sections, and a requirement-by-requirement view. #### Header, Summary Cards, and Download Actions The header shows the framework name, version, the provider scan being reviewed, and CSV / PDF download buttons. Below the header, summary cards condense the framework state at a glance: * **Requirements Status:** Donut chart with `Pass`, `Fail`, and `Manual` counts plus the total number of requirements. * **Top Failed Sections:** Ranks the sections or pillars with the highest number of failing requirements. * **ThreatScore Breakdown:** Appears only on the ThreatScore framework. It shows the overall score and per-pillar scores aligned with the ThreatScore pillars (IAM, Attack Surface, Logging and Monitoring, Encryption). The same layout applies to every compliance framework. ThreatScore is the only framework that includes the extra Breakdown card on the left; for any other framework, the Requirements Status and Top Failed Sections cards span the full row. ![Prowler ThreatScore detail page including the extra Breakdown card alongside Requirements Status and Top Failed Sections](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-threatscore-detail.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=2b399890591a03de2b8a5f9820ed14ad) ![CIS framework detail page showing only the Requirements Status donut and the Top Failed Sections card, without the ThreatScore Breakdown](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-detail-header.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=db74a215295c265c9d79521f30d339c5) #### Requirements Accordion Below the summary cards, an accordion organizes every requirement of the framework. Expand a section to see: * **Requirement ID and title:** Reflect the official identifier from the framework. * **Pass / Fail / Manual badges:** Indicate the status of each requirement based on the underlying checks. * **Custom details panel:** Opens additional context tailored to the framework. For frameworks with custom layouts, the panel surfaces fields such as control objectives, severity, attack tactics, regulatory references, or required evidence. Select a requirement to open the detail panel and review the failing checks, the resources affected, and remediation guidance. ![Expanded CIS requirement showing description, rationale, remediation procedure, audit procedure, profile and assessment tags, references, and the underlying check](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-requirements-accordion.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=fbb4ee9fc200dbeb8ddd5de43fc24c77) ##### Frameworks With Custom Detail Layouts Several frameworks include enriched detail panels that highlight fields specific to the standard: * ASD Essential Eight * AWS Well-Architected Framework * BSI C5 * Cloud Controls Matrix (CSA CCM) * CIS Benchmarks * CCC (Common Cloud Controls) * ENS RD2022 * ISO 27001 * KISA ISMS-P * MITRE ATT\&CK * Prowler ThreatScore Frameworks without a custom layout fall back to the generic details panel, which still exposes the official requirement metadata captured by Prowler. ### Downloading Compliance Reports Prowler Cloud exposes two formats: * **CSV report:** Every requirement, every check, and every finding for the selected scan and filters. Available for all supported frameworks. * **PDF report:** Curated executive-style report. Currently supported for Prowler ThreatScore, ENS RD2022, NIS2, and CSA CCM. Additional PDF reports are added in subsequent Prowler releases. > [!NOTE] > > **PDF detail section is capped at the first 100 failed findings per check.** The PDF is intended as an executive/auditor document, not a raw data dump: when a check produces more than 100 failed findings the report renders the first 100 and shows a banner pointing the reader to the CSV or JSON-OCSF export for the complete list. The compliance CSV and the scan outputs are never truncated. > > The cap is configurable per deployment via the `DJANGO_PDF_MAX_FINDINGS_PER_CHECK` environment variable on the Prowler API workers; set it to `0` to disable truncation entirely. The default value of `100` keeps the PDF readable and bounded in size on enterprise-scale scans (hundreds of thousands of findings) without affecting smaller scans, where the cap is rarely reached. > > Only **failed** findings are rendered in the detail section. PASS findings for the same check are excluded at query time. The PDF surfaces what needs attention, and the CSV/JSON exports surface everything for forensic review. #### Downloading From the Detail Page Inside any framework detail page, the **CSV** and **PDF** buttons in the header trigger the same downloads as the overview dropdown. The PDF button only appears for frameworks that support it. ![Top of a framework detail page showing the CSV and PDF download buttons in the header](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/compliance/prowler-app-compliance-detail-download.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=f790c57fc03256ea54a7a15f1f76be86) > [!NOTE] > > Region filters disable the per-card download dropdown to avoid generating partial reports. Open the framework detail page when downloads scoped to a region are required, or remove the region filter to download the full report. #### Downloading the Full Scan Output To export every framework, finding, and resource at once, use the **Scan Jobs** section instead. The ZIP archive contains the CSV, JSON-OCSF, and HTML reports plus a `compliance/` subfolder with one CSV per framework. See [Prowler Cloud — Getting Started](/user-guide/tutorials/prowler-app) for details. ### API Access Every report available in the UI is also reachable through the Prowler API. The following endpoints are the most relevant: * [Retrieve a scan compliance report as CSV](https://api.prowler.com/api/v1/docs#tag/Scan/operation/scans_compliance_retrieve) * [Download a complete scan output (ZIP)](https://api.prowler.com/api/v1/docs#tag/Scan/operation/scans_report_retrieve) Use the API to integrate compliance evidence into ticketing systems, executive dashboards, or downstream pipelines. ## Prowler CLI Prowler CLI evaluates the same compliance frameworks as Prowler Cloud, and produces detailed CSV outputs alongside the standard scan results. By default, it runs every supported framework and prints a status summary at the end of the scan: ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/compliance/compliance.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=07c4e985960c2a58211fb7a1840a3860) Detailed compliance results are stored as CSV files under the `compliance/` subfolder of Prowler's output directory. ### Scan a Specific Compliance Framework To scope a scan to a single framework and get the framework-specific summary, use the `--compliance` option: ```sh theme={null} prowler --compliance ``` Standard results plus the framework breakdown are printed to the terminal. A dedicated CSV is also generated under the `compliance/` output folder. Sample output for CIS AWS 2.0: ![](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/cli/compliance/compliance-cis-sample1.png?fit=max\&auto=format\&n=su_yXbKgm6vDhiMb\&q=85\&s=624c85f4d18a0190829500317dfcb0f5) > [!NOTE] > > If Prowler cannot find a resource related with a check from a compliance requirement, that requirement is omitted from the output. ### List Available Compliance Frameworks To see which compliance frameworks are covered by a given provider, use the `--list-compliance` option: ```sh theme={null} prowler --list-compliance ``` The full catalog is also browsable at [Prowler Hub](https://hub.prowler.com/compliance). ### List Requirements of a Compliance Framework To inspect the requirements that compose a specific framework, use the `--list-compliance-requirements` option: ```sh theme={null} prowler --list-compliance-requirements ``` Sample output for the first requirements of CIS 1.5 for AWS: ``` Listing CIS 1.5 AWS Compliance Requirements: Requirement Id: 1.1 - Description: Maintain current contact details - Checks: account_maintain_current_contact_details Requirement Id: 1.2 - Description: Ensure security contact information is registered - Checks: account_security_contact_information_is_registered Requirement Id: 1.3 - Description: Ensure security questions are registered in the AWS account - Checks: account_security_questions_are_registered_in_the_aws_account Requirement Id: 1.4 - Description: Ensure no 'root' user account access key exists - Checks: iam_no_root_access_key Requirement Id: 1.5 - Description: Ensure MFA is enabled for the 'root' user account - Checks: iam_root_mfa_enabled [redacted] ``` ## Contributing New Compliance Frameworks To request a new framework or contribute one, see [Creating a New Security Compliance Framework in Prowler](/developer-guide/security-compliance-framework). The developer guide covers the Pydantic schema, JSON catalog, output formatter, and PR submission steps required to ship a new framework end to end. ## Related Documentation * [Cross-Provider Type Compliance](/user-guide/compliance/tutorials/cross-provider-type-compliance) * [Cross-Provider Compliance](/user-guide/compliance/tutorials/cross-provider-compliance) * [Prowler ThreatScore](/user-guide/compliance/tutorials/threatscore) * [Creating a New Security Compliance Framework in Prowler](/developer-guide/security-compliance-framework) * [Prowler Cloud — Getting Started](/user-guide/tutorials/prowler-app) # Cross-Provider Compliance Source: https://docs.prowler.com/user-guide/compliance/tutorials/cross-provider-compliance Aggregate a single-provider compliance framework across every provider of the same type, review the consolidated roll-up and per-provider coverage, and download a combined PDF report. [Added in:  5.37.0](https://github.com/prowler-cloud/prowler/releases/tag/5.37.0) Cross-Provider Compliance aggregates one **single-provider compliance framework** — CIS AWS, CIS GCP, ENS for Azure — across every provider of that type into a single view. It answers the question a per-scan report cannot: **"How compliant is my whole AWS estate against CIS AWS, together?"** > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). This view is the sibling of [Cross-Provider Type Compliance](/user-guide/compliance/tutorials/cross-provider-type-compliance), which aggregates a *universal* framework across different provider types. Both live in the **Multiple Scans** tab and share the same roll-up rules, scan selection, and report flow. Only the column axis changes, from provider type to individual provider. ## How Cross-Provider Compliance Works For a chosen framework and provider type, Prowler Cloud: 1. Selects **one scan per provider**: the latest completed scan of every provider of that type you are allowed to see. 2. Aggregates the requirement results across those scans. 3. Computes a **roll-up status** for each requirement and an overall pass / fail / manual summary. 4. Exposes a **per-provider breakdown** so a failing provider is immediately attributable. ## Accessing the Cross-Provider View **1. Open the Compliance section** Sign in to Prowler Cloud at [cloud.prowler.com](https://cloud.prowler.com/sign-in) and select **Compliance** from the left navigation. **2. Open the Multiple Scans tab** **Multiple Scans** is the landing tab of the Compliance page in Prowler Cloud. Scroll to the **Across providers** section, below the **Across provider types** cards. **3. Expand a provider type** Each provider type is a collapsible group headed by its counts (frameworks available and providers registered). Expanding it reveals one card per single-provider framework available for that type. ![Multiple Scans tab showing the Across provider types cards and the Across providers section, with the AWS group collapsed and its framework and provider counts](https://mintcdn.com/prowler/_bR7OQCOgzpI3Jqp/images/compliance/prowler-app-compliance-multiple-scans.png?fit=max\&auto=format\&n=_bR7OQCOgzpI3Jqp\&q=85\&s=6939665e5a93226e58d337f2a8f5b18d) > [!NOTE] > > A provider type appears only when it has two or more providers registered **and** at least one of them has a completed scan: that scan is where the framework catalog of the provider type is read from. With a single provider the aggregation is identical to the standard per-scan [Compliance](/user-guide/compliance/tutorials/compliance) view. Framework cards in this section carry no score: they enumerate which frameworks can be aggregated for a provider type, and the roll-up numbers are computed on the detail page. Two catalogs stay out of the section, because each already has its own view: * **Universal frameworks:** Aggregated in the **Across provider types** section above. See [Cross-Provider Type Compliance](/user-guide/compliance/tutorials/cross-provider-type-compliance). * **Prowler ThreatScore:** Reviewed per scan in the **Single Scan** tab. See [Prowler ThreatScore](/user-guide/compliance/tutorials/threatscore). ![Across providers section with the AWS group expanded, showing one card per single-provider framework with its View across providers link and provider count](https://mintcdn.com/prowler/y2Qml-1Q66KeL6CI/images/compliance/prowler-app-across-providers-expanded.png?fit=max\&auto=format\&n=y2Qml-1Q66KeL6CI\&q=85\&s=0cece100375e4d192af0a0e736fff533) ## Pinning Frameworks to the Watchlist [Added in:  5.38.0](https://github.com/prowler-cloud/prowler/releases/tag/5.38.0) Framework cards inside each provider type group carry a pin button that adds the framework to the organization's [Compliance Watchlist](/user-guide/compliance/tutorials/compliance#tracking-frameworks-with-the-compliance-watchlist). With the **Show only watchlist** toggle enabled, each group lists only its pinned frameworks, and a group whose frameworks are all filtered out explains that no pinned framework matches instead of expanding into an empty accordion. ![Multiple Scans tab with Show only watchlist enabled, where the AWS group of the Across providers section lists only its pinned framework](https://mintcdn.com/prowler/hxdg66D95nJJyk4c/images/compliance/prowler-app-compliance-watchlist-filtered.png?fit=max\&auto=format\&n=hxdg66D95nJJyk4c\&q=85\&s=e2c552647f0d612bfcb84d1b7e2ea2d6) ## Which Providers Are Listed and Which Contribute The **Across providers** section and the detail page count different things, so their numbers often differ: * The section describes your **catalog**: the group header and each framework card report how many providers of that type exist in Prowler Cloud, after the filters you applied. * The detail page describes your **evidence**: only providers with a completed scan become a column in the aggregation, because every number on that page is computed from scan results. A card can therefore read `17 providers` while its detail page reports two providers aggregated from two scans. The other 15 providers exist in Prowler Cloud but have no completed scan, so there is nothing of theirs to aggregate. This is the expected state right after onboarding an AWS Organization: the discovery wizard registers every member it finds in the organization as a provider, and providers not scanned yet count toward the catalog while contributing nothing to the roll-up. See [AWS Organizations](/user-guide/tutorials/prowler-cloud-aws-organizations) for that onboarding flow. What decides whether a provider contributes is **having a completed scan**, not its connection status: * **Completed scans only:** Failed, cancelled, and in-progress scans are ignored, so a provider whose latest scan is still running keeps contributing its previous completed one. * **Disconnected providers still count:** A provider whose credentials stopped working contributes its last completed scan. The posture it shows is as old as that scan. * **Newly connected providers do not:** A provider contributes nothing until its first scan completes. To confirm which providers made it into an aggregation, read the coverage summary in the detail page header and the coverage card, which lists one row per contributing provider. > [!WARNING] > > The **Providers** filter on the detail page lists every provider of the type, including ones that have never been scanned. Narrowing to providers with no completed scan leaves the view with no evidence to aggregate: the coverage card reports nothing scanned, requirements show no per-provider status, and any report generated for that selection is empty. Clear the filter or select providers that have already been scanned. ## Working With the Framework Detail Page Selecting a card opens a detail page with the same layout as the cross-provider-type detail, with the column axis swapped from provider type to provider: * **Header:** States the framework, the provider type, and the real coverage behind the numbers, as a count of aggregated providers and scans. The **Report** button generates the combined PDF. * **Requirements Status:** Donut chart with the consolidated `Pass`, `Fail`, and `Manual` counts. * **Coverage card:** Ranks each contributing provider's individual posture, so the weakest one is visible at a glance. Every row is one provider of the type, labeled with its alias and unique identifier (UID). * **Top Failed Sections:** Ranks the framework sections with the most failing requirements, with deep links into the requirements accordion. * **Requirements accordion:** Each requirement shows its roll-up badge plus the status of every contributing provider, labeled with the provider alias and unique identifier (UID). With one or two providers the statuses appear as inline chips; from three onwards the row condenses into per-status counts (for example, `Fail ×3 Pass ×6`), and selecting the counts opens the full provider-by-provider breakdown. Expanding a requirement queries the findings of every contributing scan and merges them into a single table. ![Cross-Provider Compliance detail page for CIS AWS 7.0 showing the header with the aggregated providers and scans, the Report button, the Providers and Provider group filters, and the Requirements Status, coverage, and Top Failed Sections cards above the requirements accordion](https://mintcdn.com/prowler/y2Qml-1Q66KeL6CI/images/compliance/prowler-app-across-providers-detail.png?fit=max\&auto=format\&n=y2Qml-1Q66KeL6CI\&q=85\&s=cb3f17d7b0b131e8d19670972f8f60b4) > [!NOTE] > > Checks are not labeled per provider type as in the cross-provider-type view. Every provider of the same type shares one check set, so a single list of checks covers the whole aggregation. ### Filtering the Roll-Up Two filters control which providers feed the aggregation: * **Providers:** Narrow to specific providers of the type, listed by alias and UID. * **Provider group:** Narrow to the providers belonging to one or more provider groups. The provider type is fixed by the framework, so there is no type filter here. Filters applied on the overview carry through into the detail page and the PDF report. ## Understanding the Roll-Up Status Results roll up in two stages, with a strict **FAIL > PASS > MANUAL** precedence. **Per provider, per requirement:** * If any check fails → the provider contributes **FAIL** for that requirement. * Else if every check passes → **PASS**. * Otherwise (no pass/fail evidence) → **MANUAL**. **Across providers, per requirement (the roll-up badge):** * If at least one contributing provider is **FAIL** → the requirement is **FAIL**. * Else if at least one contributing provider is **PASS** → **PASS**. * Otherwise → **MANUAL**. > [!NOTE] > > Only providers that **actually contributed a result** for a requirement are counted. A provider whose scan produced no result for a specific requirement does not degrade that requirement to Manual, which keeps the roll-up focused on real evidence. Scan selection and permission scoping match the cross-provider-type view: the aggregation always reflects each provider's most recent completed scan, restricted to the providers your role is allowed to see. To review how provider visibility is granted, see [Role-Based Access Control (RBAC)](/user-guide/tutorials/prowler-app-rbac). ## Downloading the Combined PDF Report The **Report** button produces a single PDF across every contributing provider of the type: a cover page listing the providers, an executive summary with the consolidated roll-up, charts, a requirements index, and detailed findings grouped by requirement and provider. ![Report dropdown on the Cross-Provider Compliance detail page showing the Generate new report option](https://mintcdn.com/prowler/_bR7OQCOgzpI3Jqp/images/compliance/prowler-app-across-providers-report.png?fit=max\&auto=format\&n=_bR7OQCOgzpI3Jqp\&q=85\&s=39d2805010e65bc26f478c8a78d51483) Generation is asynchronous and behaves exactly like the cross-provider-type report — background job, toast notification when ready, and **Report → Download latest** to reuse a report already generated for the current filters. See [Downloading the Combined PDF Report](/user-guide/compliance/tutorials/cross-provider-type-compliance#downloading-the-combined-pdf-report) for the full flow, including report reuse and the findings cap. > [!NOTE] > > A report is tied to the exact set of scans it was built from. When any contributing provider completes a new scan, the previous report no longer matches the current selection and Prowler Cloud offers to generate an up-to-date one. ## Related Documentation * [Cross-Provider Type Compliance](/user-guide/compliance/tutorials/cross-provider-type-compliance) * [Compliance](/user-guide/compliance/tutorials/compliance) * [AWS Organizations](/user-guide/tutorials/prowler-cloud-aws-organizations) * [Prowler ThreatScore](/user-guide/compliance/tutorials/threatscore) # Cross-Provider Type Compliance Source: https://docs.prowler.com/user-guide/compliance/tutorials/cross-provider-type-compliance Aggregate a universal compliance framework across every compatible provider with a completed scan, review the consolidated roll-up and per-provider breakdown, and download a combined PDF report. [Added in:  5.34.0](https://github.com/prowler-cloud/prowler/releases/tag/5.34.0) Cross-Provider Type Compliance consolidates a single **universal compliance framework** across your compatible providers with completed scans into one unified view. Instead of reviewing the same framework on AWS, Azure, Google Cloud, and other supported providers as separate reports, Prowler takes the most recent completed scan of every compatible provider, aggregates them by requirement, and produces a single roll-up posture with a per-provider breakdown and a combined executive PDF. > [!NOTE] > > This feature is available exclusively in **Prowler Cloud** and **Prowler Private Cloud** with a [subscription](https://prowler.com/pricing). ## What Is a Universal Compliance Framework Most Prowler compliance frameworks target a single provider (for example, CIS AWS or CIS Azure). A **universal** framework declares its requirements once in a single JSON and maps each requirement to checks for many providers at the same time, so the same CSA CCM control maps to both AWS and Azure checks. Universal frameworks live at the top of the compliance catalog (`prowler/compliance/.json`), as opposed to the legacy per-provider frameworks under `prowler/compliance//`. For real definitions, see [`csa_ccm_4.0.json`](https://github.com/prowler-cloud/prowler/blob/master/prowler/compliance/csa_ccm_4.0.json), [`cis_controls_8.1.json`](https://github.com/prowler-cloud/prowler/blob/master/prowler/compliance/cis_controls_8.1.json), and [`dora_2022_2554.json`](https://github.com/prowler-cloud/prowler/blob/master/prowler/compliance/dora_2022_2554.json) in the Prowler repository. Prowler currently ships three universal frameworks: [CSA CCM](https://hub.prowler.com/compliance/csa_ccm_4.0), [CIS Controls](https://hub.prowler.com/compliance/cis_controls_8.1), and [DORA](https://hub.prowler.com/compliance/dora_2022_2554). Each framework page on Prowler Hub lists the full requirement-to-check mapping per provider. ## How Cross-Provider Type Compliance Works Cross-Provider Type Compliance uses this structure to answer a single question: **"How compliant is my whole estate against this framework, regardless of provider?"** For a chosen universal framework, Prowler Cloud: 1. Selects **one scan per compatible provider**: by default, the latest completed scan of each provider the framework supports and that you are allowed to see. 2. Aggregates the requirement results across those scans, folding multiple providers of the same type together. 3. Computes a **roll-up status** for each requirement and an overall pass / fail / manual summary for the framework. 4. Exposes a **per-provider breakdown** so you can see exactly which provider is failing a given control. > [!NOTE] > > Cross-Provider Type Compliance never mixes different frameworks. It aggregates one universal framework at a time across providers. To review a single provider in isolation, use the standard per-scan [Compliance](/user-guide/compliance/tutorials/compliance) view. ### Supported Universal Frameworks The Cross-Provider Type Compliance view currently supports the following universal frameworks. The compatible providers are the ones each framework declares checks for; a provider only contributes to the roll-up when it has a completed scan. | Framework | Version | Compatible providers | | - | - | - | | [**CSA CCM**](https://hub.prowler.com/compliance/csa_ccm_4.0) (Cloud Controls Matrix) | 4.0 | AWS, Azure, Google Cloud, Alibaba Cloud, Oracle Cloud | | [**CIS Controls**](https://hub.prowler.com/compliance/cis_controls_8.1) | 8.1 | AWS, Azure, Google Cloud, Microsoft 365, Kubernetes, GitHub, Google Workspace, Okta, Oracle Cloud, Alibaba Cloud, Cloudflare, MongoDB Atlas, OpenStack, Vercel | | [**DORA**](https://hub.prowler.com/compliance/dora_2022_2554) (Digital Operational Resilience Act) | 2022/2554 | AWS, Azure, Google Cloud, Alibaba Cloud, Cloudflare | The catalog grows as new universal frameworks ship in Prowler. Browse the full compliance catalog at [Prowler Hub](https://hub.prowler.com/compliance). ## Accessing the Cross-Provider Type View **1. Open the Compliance section** Sign in to Prowler Cloud at [cloud.prowler.com](https://cloud.prowler.com/sign-in) and select **Compliance** from the left navigation. **2. Open the Multiple Scans tab** In Prowler Cloud, **Multiple Scans** is the landing tab of the Compliance page, so it opens already selected. Select **Single Scan** at the top of the page to return to the per-scan compliance experience, which remains unchanged. > [!NOTE] > > The **Across provider types** section requires at least one completed scan for a provider compatible with a universal framework. If none is available, that section shows a notice prompting you to launch or wait for a scan to complete. The **Across providers** section below it has its own requirements — see [Cross-Provider Compliance](/user-guide/compliance/tutorials/cross-provider-compliance). ## Exploring the Overview The Multiple Scans tab is organized into two sections, each labeled with the axis it aggregates across: * **Across provider types:** One card per supported universal framework, aggregating every compatible provider type. This is the Cross-Provider Type Compliance experience described in the rest of this guide. * **Across providers:** One card per single-provider framework (for example, CIS AWS) that can be aggregated across every provider of the same type. See [Cross-Provider Compliance](/user-guide/compliance/tutorials/cross-provider-compliance). The **Across provider types** section presents one card per supported universal framework, each summarizing the consolidated posture across every contributing provider. ![Multiple Scans tab showing the provider filters, the Across provider types grid (CSA CCM, CIS Controls, DORA) with per-provider chips, scores, and failed and manual counts, and the Across providers section below it](https://mintcdn.com/prowler/_bR7OQCOgzpI3Jqp/images/compliance/prowler-app-compliance-multiple-scans.png?fit=max\&auto=format\&n=_bR7OQCOgzpI3Jqp\&q=85\&s=6939665e5a93226e58d337f2a8f5b18d) Each **framework card** includes: * **Framework logo, name, and version:** Identifies the universal standard (CSA CCM, CIS Controls, DORA). * **Score:** The percentage of passing requirements over the total evaluated, aggregated across every contributing provider. Color coding follows three thresholds: red for severely low compliance, amber for partial compliance, and green for healthy posture. * **Passing Requirements:** A `passed / total` counter with the aggregated roll-up. * **Provider chips:** One icon per compatible provider. Providers with a completed scan appear active with their passing percentage; providers without a scan appear dimmed with a "no completed scan yet" tooltip so coverage gaps are obvious at a glance. * **Failed and manual counts:** The number of failing and manual requirements in the roll-up. Select any card to open the framework detail page. ### Pinning Universal Frameworks to the Watchlist [Added in:  5.38.0](https://github.com/prowler-cloud/prowler/releases/tag/5.38.0) Each universal framework card carries a pin button that adds the framework to the organization's [Compliance Watchlist](/user-guide/compliance/tutorials/compliance#tracking-frameworks-with-the-compliance-watchlist). A universal framework is a single watchlist entry, so pinning it here also shows it as pinned on the Single Scan grid of every compatible provider. The **Show only watchlist** toggle above the tabs narrows both sections of the Multiple Scans tab to the pinned frameworks. ![Multiple Scans tab with the watchlist controls above the tabs and a filled pin on each universal framework card](https://mintcdn.com/prowler/hxdg66D95nJJyk4c/images/compliance/prowler-app-compliance-watchlist-pins.png?fit=max\&auto=format\&n=hxdg66D95nJJyk4c\&q=85\&s=172a2c5f0db00e4cfbf80dc0838f1c32) ### Filtering the Roll-Up The filters bar controls which providers feed every card and detail view. Cross-Provider Type Compliance supports three filters: * **Provider type:** Narrow the roll-up to specific provider types (for example, only AWS and Azure). * **Providers:** Narrow to specific providers, listed by alias and unique identifier (UID). * **Provider group:** Narrow to the providers belonging to one or more provider groups. Select **Clear filters** to reset all filters. Filters applied on the overview are carried through into the detail page and the PDF report so the view stays consistent end to end. > [!NOTE] > > Filters narrow **which providers contribute** to the aggregation. They do not change how a requirement rolls up (see [Understanding the Roll-Up Status](#understanding-the-roll-up-status)). ## Working With the Framework Detail Page The detail page provides the full breakdown for a single universal framework: aggregate metrics, provider coverage, top failing sections, and a requirement-by-requirement view with per-provider status. ![Cross-Provider Type Compliance detail page for CSA CCM 4.0 showing the header with providers scanned and the Report button, the filters, and the Requirements Status, Provider Coverage, and Top Failed Sections summary cards](https://mintcdn.com/prowler/WqX2PPr1ePaFV8hr/images/compliance/prowler-app-cross-provider-detail.png?fit=max\&auto=format\&n=WqX2PPr1ePaFV8hr\&q=85\&s=beef1e9fc40a1da34d9ae0f7b345df56) ### Header The header shows the framework name and version, a link to the framework page on [Prowler Hub](https://hub.prowler.com/compliance), and a summary such as *"X of Y compatible providers scanned · N scans aggregated"* so you always know the coverage behind the numbers. The **Report** button in the top-right generates and downloads the combined PDF (see [Downloading the Combined PDF Report](#downloading-the-combined-pdf-report)). ### Summary Cards Below the header, three summary cards condense the framework state: * **Requirements Status:** Donut chart with `Pass`, `Fail`, and `Manual` counts plus the total number of requirements, reflecting the consolidated roll-up. * **Provider Coverage:** Shows which compatible providers contributed a scan and their individual posture, so coverage gaps and per-provider weak spots are visible at a glance. * **Top Failed Sections:** Ranks the framework sections with the highest number of failing requirements, with deep links into the requirements accordion. ### Requirements Accordion The accordion organizes every requirement of the framework. For each requirement you see: * **Requirement ID and title:** The official identifier from the framework. * **Roll-up status badge:** A single `Pass`, `Fail`, or `Manual` badge representing the consolidated status across all contributing providers. * **Per-provider status:** The status each contributing provider returned for that requirement, so a single failing provider is immediately attributable. Up to five providers are shown as inline chips; beyond that the row condenses into per-status counts (for example, `Fail ×3 Pass ×6`), and selecting the counts opens the full provider-by-provider breakdown. * **Provider-labeled checks:** When you expand a requirement, the underlying checks are labeled with the provider they belong to (each universal requirement maps to different check IDs per provider). Expand a requirement to review the failing checks per provider, the affected resources, and remediation guidance. Findings are queried across every contributing scan and merged into a single table. ![Expanded DORA requirement showing the per-provider Fail badges for AWS, Azure, and Google Cloud, the requirement description and attributes, the checks count, and the merged findings table with a Provider column](https://mintcdn.com/prowler/WqX2PPr1ePaFV8hr/images/compliance/prowler-app-cross-provider-requirements-accordion.png?fit=max\&auto=format\&n=WqX2PPr1ePaFV8hr\&q=85\&s=9746ea81bc892d28ccfc6c5f78a45b49) ## Understanding the Roll-Up Status Cross-Provider Type Compliance rolls up results in two stages, with a strict **FAIL > PASS > MANUAL** precedence. **Per provider, per requirement:** * If any check fails → the provider contributes **FAIL** for that requirement. * Else if every check passes → **PASS**. * Otherwise (no pass/fail evidence) → **MANUAL**. Multiple providers of the same type (for example, three AWS providers) are folded together first, so a failure in any one of them marks that provider type as failing. **Across providers, per requirement (the roll-up badge):** * If at least one contributing provider is **FAIL** → the requirement is **FAIL**. * Else if at least one contributing provider is **PASS** → **PASS**. * Otherwise → **MANUAL**. > [!NOTE] > > Only providers that **actually contributed a result** for a requirement are counted. A provider that has a scan in the aggregation but produced no result for a specific requirement (for example, because the framework maps no checks to that provider for that control) does **not** degrade the requirement to Manual. This keeps the roll-up focused on real evidence. ### How Scans Are Selected By default, Cross-Provider Type Compliance auto-selects the **latest completed scan** of each compatible provider you are allowed to see. This means: * The view always reflects your most recent posture per provider, without any manual scan selection. * Adding a new compatible provider and running a scan automatically brings it into the roll-up. * Provider visibility follows your role: only the providers your permissions allow are ever shown, and the roll-up is scoped accordingly. See [Role-Based Access Control (RBAC)](/user-guide/tutorials/prowler-app-rbac). What makes a provider contribute is **having a completed scan**, not its current connection status: * Only scans in the **completed** state are eligible. Failed, cancelled, and in-progress scans are ignored, so a provider whose latest scan is still running keeps contributing its previous completed one. * A provider whose credentials stopped working still contributes its last completed scan. The posture it shows is as old as that scan. * A provider connected but never scanned contributes nothing until its first scan completes. On the framework cards it appears dimmed instead of disappearing, so the coverage gap stays visible. ## Downloading the Combined PDF Report The **Report** button on the detail page generates a single PDF that combines every contributing provider's latest scan for the framework into one executive document: a cover page listing every contributing provider, an executive summary with the consolidated roll-up, charts, a requirements index, and detailed findings grouped by requirement and provider. ### The Report Follows Your Filters A report covers the exact set of scans your current filters resolve to. The provider type, providers, and provider group filters applied on the detail page determine which providers contribute, and the auto-select rule pins each contributing provider's latest completed scan. The PDF is built from that resolved scan set together with the framework. As a result, each filter combination produces its own report. For example: * No filters → a report covering every compatible provider that has a completed scan. * `Provider type = AWS, Azure` → a report covering only your AWS and Azure scans. * `Provider group = Production` → a report covering only the providers in that group. Changing the filters and generating again produces a different, independent report. Each combination is tracked on its own, so switching filters back and forth never overwrites a previously generated report. > [!NOTE] > > Region filtering is **not** supported for the combined PDF report. The report recomputes status live across every region of the contributing scans, so a region-scoped request is rejected rather than producing a report that contradicts a region-filtered view. ### Generating and Reusing a Report Because the report aggregates many scans, it is generated **asynchronously**: **1. Start the report** Select **Report → Generate new report…**, optionally give it a name, and confirm. Prowler starts a background job and shows a "Report generation started" confirmation. **2. Wait for completion** The button shows a "Generating report…" state while the job runs. Generation continues in the background: you can navigate away, and a toast notification appears when the report is ready, even after a page reload. **3. Download** When the report is ready, select **Download** from the notification, or use **Report → Download latest** at any time to fetch the most recent report for the current filters. ![Report dropdown on the Cross-Provider Type Compliance detail page showing the Generate new report option](https://mintcdn.com/prowler/WqX2PPr1ePaFV8hr/images/compliance/prowler-app-cross-provider-report.png?fit=max\&auto=format\&n=WqX2PPr1ePaFV8hr\&q=85\&s=df0601e80c94df9015336a069e50b0be) A report already generated for a given set of filters does not need to be generated again. When you open the detail page with a filter combination that was reported before, Prowler detects the existing report and surfaces **Report → Download latest** so you can download it immediately, without launching a new job. You only need to generate a fresh report when: * You apply a filter combination that has never been reported before, or * A contributing provider has completed a new scan since the report was generated. The report is tied to the specific scans it was built from, so a newer completed scan makes the previous report stale; Prowler recognizes it no longer matches the current selection and offers to generate an up-to-date one. "Download latest" reuses an existing report only when it matches the framework, the exact resolved scan set for the current filters, and the same report options. This guarantees the PDF you download reflects the posture you are looking at, rather than a report generated for a different filter or an older scan. > [!NOTE] > > The PDF detail section renders only **failed** requirements by default so the report stays focused as an executive/auditor document. As with every Prowler PDF, the detail section is capped at the first 100 failed findings per check; use the per-scan CSV or JSON-OCSF exports for the complete, untruncated list. See [Downloading Compliance Reports](/user-guide/compliance/tutorials/compliance#downloading-compliance-reports) for the full PDF behavior and the `DJANGO_PDF_MAX_FINDINGS_PER_CHECK` setting. ## Aggregating a Single-Provider Framework Across Providers Universal frameworks answer the cross-provider-type question, but most compliance frameworks target a single provider type — CIS AWS, CIS GCP, ENS for Azure. The **Across providers** section of the Multiple Scans tab answers the sibling question for those frameworks: **"How compliant is my whole AWS estate against CIS AWS, together?"** The aggregation works the same way, with the column axis swapped from provider type to individual provider, and it produces its own combined PDF report. See [Cross-Provider Compliance](/user-guide/compliance/tutorials/cross-provider-compliance) for the full guide. ## Related Documentation * [Cross-Provider Compliance](/user-guide/compliance/tutorials/cross-provider-compliance) * [Compliance](/user-guide/compliance/tutorials/compliance) * [Prowler ThreatScore](/user-guide/compliance/tutorials/threatscore) * [Creating a New Security Compliance Framework in Prowler](/developer-guide/security-compliance-framework) * [Prowler Cloud — Getting Started](/user-guide/tutorials/prowler-app) # Prowler ThreatScore Source: https://docs.prowler.com/user-guide/compliance/tutorials/threatscore ## Introduction Prowler ThreatScore is a comprehensive compliance scoring system that provides a unified metric for assessing security posture across compliance frameworks. It aggregates findings from individual security checks into a single, normalized score ranging from 0 to 100. ### Purpose * **Unified view:** A single metric represents overall compliance health. * **Risk prioritization:** Highlights which areas pose the highest security risks. * **Progress tracking:** Monitors improvements in compliance posture over time. * **Executive reporting:** Delivers clear, quantifiable security metrics to stakeholders. ## How ThreatScore Works The ThreatScore calculation considers four critical factors for each compliance requirement: ### 1. Pass Rate (`rate_i`) The percentage of security checks that passed for a specific requirement: ``` Pass Rate = (Number of PASS findings) / (Total findings) ``` ### 2. Total Findings (`total_i`) The total number of checks performed (both PASS and FAIL) for a requirement. This represents the amount of evidence available - more findings provide greater confidence in the assessment. ### 3. Weight (`weight_i`) A numerical value (1-1000) representing the business importance or criticality of the requirement within the organizational context. ### 4. Risk Level (`risk_i`) A severity rating (1-5) indicating the potential impact of non-compliance with this requirement. ## Score Interpretation Guidelines | ThreatScore | Interpretation | Recommended Actions | | - | - | - | | 90-100% | Excellent | Maintain current controls, focus on continuous improvement | | 80-89% | Good | Address remaining gaps, prepare for compliance audits | | 70-79% | Acceptable | Prioritize high-risk failures, develop improvement plan | | 60-69% | Needs Improvement | Immediate attention required, may not pass compliance audit | | Below 60% | Critical | Emergency response needed, potential regulatory issues | ## Mathematical Formula The ThreatScore uses a weighted average formula that accounts for all four factors: ``` ThreatScore = (Σ(rate_i × total_i × weight_i × risk_i) / Σ(total_i × weight_i × risk_i)) × 100 ``` ### Formula Properties * **Normalization**: Always produces a score between 0 and 100 * **Evidence-weighted**: Requirements with more findings have proportionally greater influence * **Risk-sensitive**: Higher risk requirements impact the score more significantly * **Business-aligned**: Weight values allow customization based on organizational priorities ## Parameters Explained ### Weight Values (1-1000) The weight parameter allows customization of ThreatScore calculation based on organizational priorities and regulatory requirements. #### Weight Assignment Guidelines | Weight Range | Priority Level | Use Cases | | - | - | - | | 1-100 | Low | Optional or nice-to-have controls | | 101-300 | Medium | Standard security practices | | 301-600 | High | Important security controls | | 601-850 | Critical | Regulatory compliance requirements | | 851-1000 | Maximum | Mission-critical security controls | #### Weight Selection Strategy 1. **Regulatory Mapping**: Assign higher weights to controls required by industry regulations 2. **Business Impact**: Consider the potential business impact of control failures 3. **Risk Tolerance**: Align weights with organizational risk appetite 4. **Stakeholder Input**: Involve compliance and business teams in weight decisions ### Risk Levels (1-5) Risk levels represent the potential security impact of non-compliance with a requirement. | Risk Level | Severity | Impact Description | | - | - | - | | 1 | Very Low | Minimal security impact, informational | | 2 | Low | Limited exposure, low probability of exploitation | | 3 | Medium | Moderate security risk, potential for limited damage | | 4 | High | Significant security risk, high probability of impact | | 5 | Critical | Severe security risk, immediate threat to organization | #### Risk Level Assessment Criteria * **Confidentiality Impact**: Data exposure potential * **Integrity Impact**: Risk of unauthorized data modification * **Availability Impact**: Service disruption potential * **Compliance Impact**: Regulatory violation consequences * **Exploitability**: Ease of exploitation by threat actors ## Security Pillars and Subpillars Prowler organizes security requirements into a hierarchical structure of pillars and subpillars, providing a comprehensive framework for security assessment and compliance evaluation. ### Security Pillars Overview The ThreatScore calculation considers requirements organized within the following security pillars: #### 1. IAM (Identity and Access Management) **Purpose**: Controls who can access what resources and under what conditions **Subpillars**: * **1.1 Authentication**: Verifying user and system identities * **1.2 Authorization**: Controlling access to resources based on authenticated identity * **1.3 Privilege Escalation**: Preventing unauthorized elevation of permissions #### 2. Attack Surface **Purpose**: Minimizing exposure points that could be exploited by threat actors across network, storage, and application layers **Subpillars**: * **2.1 Network**: Network infrastructure security, segmentation, firewall rules, VPC configurations, and traffic controls * **2.2 Storage**: Data storage systems security, database security, file system permissions, backup security, and storage encryption * **2.3 Application**: Application-level controls and configurations, application security settings, code security, runtime protections #### 3. Logging and Monitoring **Purpose**: Ensuring comprehensive visibility and audit capabilities **Subpillars**: * **3.1 Logging**: Capturing security-relevant events and activities * **3.2 Retention**: Maintaining logs for appropriate time periods * **3.3 Monitoring**: Active surveillance and alerting on security events #### 4. Encryption **Purpose**: Protecting data confidentiality through cryptographic controls **Subpillars**: * **4.1 In-Transit**: Encrypting data during transmission * **4.2 At-Rest**: Encrypting stored data ### Pillar Hierarchy and ThreatScore Impact #### Hierarchy Structure ``` Security Framework ├── 1. IAM │ ├── 1.1 Authentication │ ├── 1.2 Authorization │ └── 1.3 Privilege Escalation ├── 2. Attack Surface │ ├── 2.1 Network │ ├── 2.2 Storage │ └── 2.3 Application ├── 3. Logging and Monitoring │ ├── 3.1 Logging │ ├── 3.2 Retention │ └── 3.3 Monitoring └── 4. Encryption ├── 4.1 In-Transit └── 4.2 At-Rest Example Requirement Structure: ├── Pillar: 1. IAM │ ├── Subpillar: 1.1 Authentication │ │ ├── Requirement: MFA Implementation │ │ │ ├── Check 1: Admin accounts use MFA │ │ │ ├── Check 2: Regular users use MFA │ │ │ └── Check 3: Service accounts use MFA │ │ └── [Additional Requirements] │ └── [Additional Subpillars: Authorization, Privilege Escalation] ``` #### Weight and Risk Assignment by Pillar Different pillars typically receive different weight and risk assignments based on their security impact: | Pillar | Typical Weight Range | Typical Risk Range | Rationale | | - | - | - | - | | 1. IAM | 800-1000 | 4-5 | Critical for access control, high impact if compromised | | 2. Attack Surface | 500-900 | 3-5 | Highly dependent on exposure and criticality across network, storage, and application layers | | 3. Logging and Monitoring | 600-800 | 3-4 | Important for detection and compliance, moderate direct impact | | 4. Encryption | 700-950 | 4-5 | Essential for data protection, regulatory compliance | **Subpillar Weight Considerations**: * **2.1 Network (Attack Surface)**: 500-800, Risk 3-4 - Network perimeter defense * **2.2 Storage (Attack Surface)**: 600-900, Risk 4-5 - Data exposure impact * **2.3 Application (Attack Surface)**: 400-700, Risk 2-4 - Varies by application criticality ### Pillar-Specific Scoring Considerations #### High-Impact Pillars (1. IAM, 4. Encryption) * **Characteristics**: Direct impact on data protection and access control * **ThreatScore Impact**: Failures in these pillars significantly lower overall score * **Weight Strategy**: Assign maximum weights (800-1000) to critical requirements * **Risk Strategy**: Most requirements rated 4-5 due to severe consequences #### Variable-Impact Pillar (2. Attack Surface) * **Characteristics**: Impact varies significantly across subpillars (Network, Storage, Application) * **ThreatScore Impact**: Depends on specific subpillar and business context * **Weight Strategy**: * 2.1 Network subpillar: 500-800 (perimeter defense importance) * 2.2 Storage subpillar: 600-900 (data exposure risk) * 2.3 Application subpillar: 400-700 (application-specific criticality) * **Risk Strategy**: Wide range (2-5) based on exposure, data sensitivity, and business criticality #### Monitoring Pillar (3. Logging and Monitoring) * **Characteristics**: Essential for compliance and incident response * **ThreatScore Impact**: Moderate influence, critical for audit requirements * **Weight Strategy**: Consistent weights (600-800) across logging, retention, and monitoring subpillars * **Risk Strategy**: Moderate risk levels (3-4) with emphasis on compliance impact ### Cross-Pillar Dependencies #### Authentication ↔ Authorization (IAM) * Strong authentication enables effective authorization controls * Weight both subpillars highly as they're interdependent #### Logging ↔ Monitoring (Logging and Monitoring) * Logging provides the data that monitoring systems analyze * Balance weights to ensure both data collection and analysis are prioritized #### In-Transit ↔ At-Rest (Encryption) * Comprehensive data protection requires both encryption types * Consider data flow patterns when assigning relative weights ### Pillar Coverage in ThreatScore #### Complete Coverage Benefits * **Comprehensive Assessment**: All security domains represented in score * **Balanced View**: Prevents over-emphasis on single security aspect * **Regulatory Alignment**: Covers requirements across major compliance frameworks #### Partial Coverage Considerations * **Focused Assessment**: Target specific security domains * **Resource Optimization**: Concentrate efforts on high-priority areas * **Gradual Implementation**: Phase in additional pillars over time ## Scoring Examples ### Example 1: Basic Two-Requirement Scenario Consider a compliance framework with two requirements: **Requirement 1: Encryption at Rest** * Findings: 200 PASS, 500 FAIL (total = 700) * Pass Rate: 200/700 = 0.286 (28.6%) * Weight: 500 (High priority - data protection) * Risk Level: 4 (High risk - data exposure) **Requirement 2: Access Logging** * Findings: 300 PASS, 100 FAIL (total = 400) * Pass Rate: 300/400 = 0.75 (75%) * Weight: 800 (Critical for audit compliance) * Risk Level: 3 (Medium risk - audit trail) **Calculation:** ``` Numerator = (0.286 × 700 × 500 × 4) + (0.75 × 400 × 800 × 3) = (400,400) + (720,000) = 1,120,400 Denominator = (700 × 500 × 4) + (400 × 800 × 3) = 1,400,000 + 960,000 = 2,360,000 ThreatScore = (1,120,400 / 2,360,000) × 100 = 47.5% ``` ### Example 2: Enterprise Scenario with Pillar Structure This example demonstrates how pillar organization affects ThreatScore calculation: | Pillar | Subpillar | Requirement | Pass | Fail | Total | Weight | Risk | Pass Rate | | - | - | - | - | - | - | - | - | - | | 1. IAM | 1.2 Authorization | Access Controls | 280 | 120 | 400 | 800 | 4 | 70% | | 2. Attack Surface | 2.1 Network | Network Segmentation | 150 | 50 | 200 | 750 | 4 | 75% | | 2. Attack Surface | 2.2 Storage | Backup Security | 200 | 100 | 300 | 600 | 3 | 66.7% | | 3. Logging and Monitoring | 3.1 Logging | Audit Logging | 350 | 50 | 400 | 700 | 3 | 87.5% | | 4. Encryption | 4.2 At-Rest | Encryption | 450 | 50 | 500 | 950 | 5 | 90% | **Step-by-step Calculation:** 1. **Calculate weighted contributions for each requirement:** ``` Numerator = Σ(rate_i × total_i × weight_i × risk_i) ``` * **Access Controls (1.2 Authorization)**: 0.70 × 400 × 800 × 4 = 896,000 * **Network Segmentation (2.1 Network)**: 0.75 × 200 × 750 × 4 = 450,000 * **Backup Security (2.2 Storage)**: 0.667 × 300 × 600 × 3 = 360,060 * **Audit Logging (3.1 Logging)**: 0.875 × 400 × 700 × 3 = 735,000 * **Encryption (4.2 At-Rest)**: 0.90 × 500 × 950 × 5 = 2,137,500 2. **Sum numerator:** 2,137,500 + 896,000 + 735,000 + 360,060 + 450,000 = **4,578,560** 3. **Calculate total weights for each requirement:** ``` Denominator = Σ(total_i × weight_i × risk_i) ``` * **Access Controls (1.2 Authorization)**: 400 × 800 × 4 = 1,280,000 * **Network Segmentation (2.1 Network)**: 200 × 750 × 4 = 600,000 * **Backup Security (2.2 Storage)**: 300 × 600 × 3 = 540,000 * **Audit Logging (3.1 Logging)**: 400 × 700 × 3 = 840,000 * **Encryption (4.2 At-Rest)**: 500 × 950 × 5 = 2,375,000 4. **Sum denominator:** 2,375,000 + 1,280,000 + 840,000 + 540,000 + 600,000 = **5,635,000** 5. **Final ThreatScore calculation:** ``` ThreatScore = (Numerator / Denominator) × 100 ThreatScore = (4,578,560 / 5,635,000) × 100 = 81.2% ``` **Pillar-Level Analysis:** * **1. IAM pillar (1.2 Authorization)**: Significant impact despite lower pass rate (70%) due to high weight (800) * **2. Attack Surface pillar (2.1 Network)**: Strong performance (75%) with high weight (750) balances the score * **2. Attack Surface pillar (2.2 Storage)**: Lowest performance (66.7%) but limited impact due to moderate weight (600) * **3. Logging and Monitoring pillar (3.1 Logging)**: Moderate contribution with good performance (87.5%) * **4. Encryption pillar (4.2 At-Rest)**: Highest contribution due to maximum weight (950) and risk (5) ### Example 3: Multi-Pillar Comprehensive Scenario | Pillar | Subpillar | Requirement | Pass | Fail | Weight | Risk | Pass Rate | | - | - | - | - | - | - | - | - | | 1. IAM | 1.1 Authentication | MFA Implementation | 180 | 20 | 900 | 5 | 90% | | 1. IAM | 1.2 Authorization | Least Privilege Access | 150 | 50 | 850 | 4 | 75% | | 1. IAM | 1.3 Privilege Escalation | Admin Account Controls | 95 | 5 | 950 | 5 | 95% | | 2. Attack Surface | 2.1 Network | Firewall Configuration | 400 | 100 | 600 | 3 | 80% | | 2. Attack Surface | 2.1 Network | Public Endpoint Security | 80 | 20 | 700 | 4 | 80% | | 2. Attack Surface | 2.2 Storage | Data Classification | 300 | 100 | 650 | 3 | 75% | | 2. Attack Surface | 2.3 Application | Input Validation | 150 | 50 | 500 | 3 | 75% | | 3. Logging and Monitoring | 3.1 Logging | Transaction Logging | 500 | 50 | 750 | 3 | 90.9% | | 3. Logging and Monitoring | 3.3 Monitoring | Real-time Alerts | 200 | 50 | 700 | 4 | 80% | | 4. Encryption | 4.2 At-Rest | Database Encryption | 300 | 20 | 900 | 5 | 93.8% | | 4. Encryption | 4.1 In-Transit | API/Web Encryption | 250 | 10 | 800 | 4 | 96.2% | **Pillar Performance Summary**: * **1. IAM Pillar Average**: \~87% (weighted by findings across Authentication, Authorization, and Privilege Escalation subpillars) * **2. Attack Surface Pillar Average**: \~77% (weighted across Network, Storage, and Application subpillars) * 2.1 Network subpillar: \~80% average * 2.2 Storage subpillar: 75% * 2.3 Application subpillar: 75% * **3. Logging and Monitoring Average**: \~87% (weighted by findings across Logging and Monitoring subpillars) * **4. Encryption Pillar Average**: \~94% (weighted by findings across In-Transit and At-Rest subpillars) **Overall ThreatScore**: \~85.3% This comprehensive example demonstrates how: * High-performing, high-weight pillars (4. Encryption, 1. IAM) significantly boost the score * The 2. Attack Surface pillar shows how diverse subpillars (Network, Storage, Application) are aggregated * Multiple requirements within pillars provide detailed granular assessment * Cross-pillar balance prevents single points of failure in security posture ### Example 4: Impact of Parameter Changes Using the scenario, the following changes show how parameter adjustments affect the score: #### Scenario A: Increase Encryption Risk Level Change Encryption risk from 5 to 3: * **New ThreatScore: 77.8%** (decrease of 3.4 points) * **Impact**: Lower risk weighting reduces the influence of high-performing critical controls #### Scenario B: Improve Access Controls Pass Rate Change Access Controls from 70% to 90% pass rate: * **New ThreatScore: 85.1%** (increase of 3.9 points) * **Impact**: Improving performance on high-weight requirements has significant score impact #### Scenario C: Add New Low-Weight Requirement Add "Documentation Completeness" (50 PASS, 10 FAIL, weight=100, risk=1): * **New ThreatScore: 81.3%** (minimal change of 0.1 points) * **Impact**: Low-weight requirements have minimal impact on overall score ## Implementation Details ### Edge Cases and Special Conditions #### Zero Findings Scenario When a requirement has `total_i = 0` (no findings): * **Behavior**: Requirement is completely excluded from calculation * **Rationale**: No evidence means no contribution to confidence in the score * **Impact**: Other requirements receive proportionally more influence #### Perfect Score Scenario When all requirements have 100% pass rate: * **Result**: ThreatScore = 100% * **Interpretation**: All implemented security checks are passing #### Zero Pass Rate Scenario When all requirements have 0% pass rate: * **Result**: ThreatScore = 0% * **Interpretation**: Critical security failures across all requirements #### Single Requirement Framework For frameworks with only one requirement: * **Formula simplification**: ThreatScore = pass\_rate × 100 * **Impact**: Weight and risk values become irrelevant for score calculation ### Performance Considerations #### Computational Complexity * **Time Complexity**: O(n) where n = number of requirements * **Space Complexity**: O(1) - constant space for accumulation * **Scalability**: Efficiently handles frameworks with thousands of requirements #### Calculation Precision * **Floating Point**: Use double precision for intermediate calculations * **Rounding**: Final score rounded to 1 decimal place for display * **Overflow Protection**: Validate that weight × risk × total values don't exceed system limits ### Data Requirements #### Minimum Data Set For each requirement, the following data must be available: * **pass\_count**: Number of PASS findings (integer ≥ 0) * **fail\_count**: Number of FAIL findings (integer ≥ 0) * **weight**: Business importance (integer 1-1000) * **risk**: Risk level (integer 1-5) #### Data Validation Rules ``` total_i = pass_i + fail_i rate_i = pass_i / total_i (when total_i > 0) 1 ≤ weight_i ≤ 1000 1 ≤ risk_i ≤ 5 ``` #### Handling Invalid Data * **Negative values**: Treat as 0 and log warning * **Out-of-range weights/risk**: Clamp to valid range and log warning * **Missing data**: Exclude requirement from calculation and log warning ## Best Practices ### Monitoring and Trending 1. **Establish Baseline** * Record initial ThreatScore after implementing measurement * Set realistic improvement targets based on organizational capacity * Track score changes over time to identify trends 2. **Regular Reporting** * Generate monthly ThreatScore reports for stakeholders * Highlight significant score changes and their causes * Include requirement-level breakdowns for detailed analysis 3. **Continuous Improvement** * Use score trends to identify systematic issues * Correlate score changes with security incidents or changes * Adjust weights and risk levels based on lessons learned # Run Prowler in CI/CD and Send Findings to Prowler Cloud Source: https://docs.prowler.com/user-guide/cookbooks/cicd-pipeline > [!WARNING] > > For new projects, use the official [Prowler GitHub Action](/user-guide/tutorials/prowler-app-github-action) — a Docker-based reusable action that runs scans, optionally pushes findings to Prowler Cloud, and uploads SARIF results to GitHub Code Scanning. The GitHub Actions examples below document the legacy pip-based flow. This cookbook demonstrates how to integrate Prowler into CI/CD pipelines so that security scans run automatically and findings are sent to Prowler Cloud via [Import Findings](/user-guide/tutorials/prowler-import-findings). Examples cover GitHub Actions and GitLab CI. ## Prerequisites * A **Prowler Cloud** account with an active subscription (see [Prowler Cloud Pricing](https://prowler.com/pricing)) * A Prowler Cloud **API key** with the **Manage Ingestions** permission (see [API Keys](/user-guide/tutorials/prowler-app-api-keys)) * Cloud provider credentials configured in the CI/CD environment (e.g., AWS credentials for scanning AWS accounts) * Access to configure pipeline workflows and secrets in the CI/CD platform ## Key Concepts Prowler CLI provides the `--push-to-cloud` flag, which uploads scan results directly to Prowler Cloud after a scan completes. Combined with the `PROWLER_CLOUD_API_KEY` environment variable, this enables fully automated ingestion without manual file uploads. For full details on the flag and API, refer to the [Import Findings](/user-guide/tutorials/prowler-import-findings) documentation. > [!NOTE] > > The examples in this guide use AWS as the target provider, but the same approach applies to any provider supported by Prowler (Azure, GCP, Kubernetes, and others). Replace `prowler aws` with the desired provider command (e.g., `prowler gcp`, `prowler azure`) and configure the corresponding credentials in the CI/CD environment. ## GitHub Actions ### Store Secrets Before creating the workflow, add the following secrets to the repository (under "Settings" > "Secrets and variables" > "Actions"): * `PROWLER_CLOUD_API_KEY` — the Prowler Cloud API key * Cloud provider credentials (e.g., `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, or configure OIDC-based role assumption) ### Workflow: Scheduled AWS Scan This workflow runs Prowler against an AWS account on a daily schedule and on every push to the `main` branch: ```yaml theme={null} name: Prowler Security Scan on: schedule: - cron: "0 3 * * *" # Daily at 03:00 UTC push: branches: [main] workflow_dispatch: # Allow manual triggers permissions: id-token: write # Required for OIDC contents: read jobs: prowler-scan: runs-on: ubuntu-latest steps: - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::123456789012:role/ProwlerScanRole aws-region: us-east-1 - name: Install Prowler run: pip install prowler - name: Run Prowler Scan env: PROWLER_CLOUD_API_KEY: ${{ secrets.PROWLER_CLOUD_API_KEY }} run: | prowler aws --push-to-cloud ``` > [!NOTE] > > Replace `123456789012` with the actual AWS account ID and `ProwlerScanRole` with the IAM role name. For IAM role setup, refer to the [AWS authentication guide](/user-guide/providers/aws/authentication). ### Workflow: Scan Specific Services on Pull Request To run targeted scans on pull requests without blocking the merge pipeline, use `continue-on-error`: ```yaml theme={null} name: Prowler PR Check on: pull_request: branches: [main] jobs: prowler-scan: runs-on: ubuntu-latest continue-on-error: true steps: - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::123456789012:role/ProwlerScanRole aws-region: us-east-1 - name: Install Prowler run: pip install prowler - name: Run Prowler Scan env: PROWLER_CLOUD_API_KEY: ${{ secrets.PROWLER_CLOUD_API_KEY }} run: | prowler aws --services s3,iam,ec2 --push-to-cloud ``` > [!TIP] > > Limiting the scan to specific services with `--services` reduces execution time, making it practical for pull request checks. ## GitLab CI ### Store Variables Add the following CI/CD variables in the GitLab project (under "Settings" > "CI/CD" > "Variables"): * `PROWLER_CLOUD_API_KEY` — mark as **masked** and **protected** * Cloud provider credentials as needed ### Pipeline: Scheduled AWS Scan Add the following to `.gitlab-ci.yml`: ```yaml theme={null} prowler-scan: image: python:3.13-slim stage: test script: - pip install prowler - prowler aws --push-to-cloud variables: PROWLER_CLOUD_API_KEY: $PROWLER_CLOUD_API_KEY AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY AWS_DEFAULT_REGION: "us-east-1" rules: - if: $CI_PIPELINE_SOURCE == "schedule" - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH when: manual ``` To run the scan on a schedule, create a **Pipeline Schedule** in GitLab (under "Build" > "Pipeline Schedules") with the desired cron expression. ### Pipeline: Multi-Provider Scan To scan multiple cloud providers in parallel: ```yaml theme={null} stages: - security .prowler-base: image: python:3.13-slim stage: security before_script: - pip install prowler rules: - if: $CI_PIPELINE_SOURCE == "schedule" prowler-aws: extends: .prowler-base script: - prowler aws --push-to-cloud variables: PROWLER_CLOUD_API_KEY: $PROWLER_CLOUD_API_KEY AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY prowler-gcp: extends: .prowler-base script: - prowler gcp --push-to-cloud variables: PROWLER_CLOUD_API_KEY: $PROWLER_CLOUD_API_KEY GOOGLE_APPLICATION_CREDENTIALS: $GCP_SERVICE_ACCOUNT_KEY ``` ## Tips and Best Practices ### When to Run Scans * **Scheduled scans** (daily or weekly) provide continuous monitoring and are ideal for baseline security assessments * **On-merge scans** catch configuration changes introduced by new code * **Pull request scans** provide early feedback but should target specific services to keep execution times reasonable ### Handling Scan Failures By default, Prowler exits with a non-zero code when it finds failing checks. This causes the CI/CD job to fail. To prevent scan results from blocking the pipeline: * **GitHub Actions**: Add `continue-on-error: true` to the job * **GitLab CI**: Add `allow_failure: true` to the job > [!NOTE] > > Ingestion failures (e.g., network issues reaching Prowler Cloud) do not affect the Prowler exit code. The scan completes normally and only a warning is emitted. See [Import Findings troubleshooting](/user-guide/tutorials/prowler-import-findings#troubleshooting) for details. ### Caching Prowler Installation For faster pipeline runs, cache the Prowler installation: **GitHub Actions:** ```yaml theme={null} - name: Cache pip packages uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-prowler restore-keys: ${{ runner.os }}-pip- - name: Install Prowler run: pip install prowler ``` **GitLab CI:** ```yaml theme={null} prowler-scan: cache: paths: - .cache/pip variables: PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" ``` ### Output Formats To generate additional report formats alongside the cloud upload: ```bash theme={null} prowler aws --push-to-cloud -M csv,html -o /tmp/prowler-reports ``` This produces CSV and HTML files locally while also pushing OCSF findings to Prowler Cloud. The local files can be stored as CI/CD artifacts for archival purposes. ### Scanning Multiple AWS Accounts To scan multiple accounts sequentially in a single job, use [role assumption](/user-guide/providers/aws/role-assumption): ```bash theme={null} prowler aws -R arn:aws:iam::111111111111:role/ProwlerScanRole --push-to-cloud prowler aws -R arn:aws:iam::222222222222:role/ProwlerScanRole --push-to-cloud ``` Each scan run creates a separate ingestion job in Prowler Cloud. # Run Kubernetes In-Cluster and Send Findings to Prowler Cloud Source: https://docs.prowler.com/user-guide/cookbooks/kubernetes-in-cluster This cookbook walks through deploying Prowler inside a Kubernetes cluster on a recurring schedule and automatically sending findings to Prowler Cloud via [Import Findings](/user-guide/tutorials/prowler-import-findings). By the end, security scan results from the cluster appear in Prowler Cloud without any manual file uploads. ## Prerequisites * A **Prowler Cloud** account with an active subscription (see [Prowler Cloud Pricing](https://prowler.com/pricing)) * A Prowler Cloud **API key** with the **Manage Ingestions** permission (see [API Keys](/user-guide/tutorials/prowler-app-api-keys)) * Access to a Kubernetes cluster with `kubectl` configured * Permissions to create ServiceAccounts, Roles, RoleBindings, Secrets, and CronJobs in the cluster ## Step 1: Create the ServiceAccount and RBAC Resources Prowler needs a ServiceAccount with read access to cluster resources. Apply the manifests from the [`kubernetes` directory](https://github.com/prowler-cloud/prowler/tree/master/kubernetes) of the Prowler repository: ```console theme={null} kubectl apply -f kubernetes/prowler-sa.yaml kubectl apply -f kubernetes/prowler-role.yaml kubectl apply -f kubernetes/prowler-rolebinding.yaml ``` This creates: * A `prowler-sa` ServiceAccount in the `prowler-ns` namespace * A ClusterRole with the read permissions Prowler requires * A ClusterRoleBinding linking the ServiceAccount to the role For more details on these resources, refer to [Getting Started with Kubernetes](/user-guide/providers/kubernetes/getting-started-k8s). ## Step 2: Store the Prowler Cloud API Key as a Secret Create a Kubernetes Secret to hold the API key securely: ```console theme={null} kubectl create secret generic prowler-cloud-api-key \ --from-literal=api-key=pk_your_api_key_here \ --namespace prowler-ns ``` Replace `pk_your_api_key_here` with the actual API key from Prowler Cloud. > [!WARNING] > > Avoid embedding the API key directly in the CronJob manifest. Using a Kubernetes Secret keeps credentials out of version control and pod specs. ## Step 3: Create the CronJob Manifest The CronJob runs Prowler on a schedule, scanning the cluster and pushing findings to Prowler Cloud with the `--push-to-cloud` flag. Create a file named `prowler-cronjob.yaml`: ```yaml theme={null} apiVersion: batch/v1 kind: CronJob metadata: name: prowler-k8s-scan namespace: prowler-ns spec: schedule: "0 2 * * *" # Runs daily at 02:00 UTC concurrencyPolicy: Forbid jobTemplate: spec: backoffLimit: 1 template: metadata: labels: app: prowler spec: serviceAccountName: prowler-sa containers: - name: prowler image: prowlercloud/prowler:stable args: - "kubernetes" - "--push-to-cloud" env: - name: PROWLER_CLOUD_API_KEY valueFrom: secretKeyRef: name: prowler-cloud-api-key key: api-key - name: CLUSTER_NAME value: "my-cluster" imagePullPolicy: Always volumeMounts: - name: var-lib-cni mountPath: /var/lib/cni readOnly: true - name: var-lib-etcd mountPath: /var/lib/etcd readOnly: true - name: var-lib-kubelet mountPath: /var/lib/kubelet readOnly: true - name: etc-kubernetes mountPath: /etc/kubernetes readOnly: true hostPID: true restartPolicy: Never volumes: - name: var-lib-cni hostPath: path: /var/lib/cni - name: var-lib-etcd hostPath: path: /var/lib/etcd - name: var-lib-kubelet hostPath: path: /var/lib/kubelet - name: etc-kubernetes hostPath: path: /etc/kubernetes ``` > [!NOTE] > > Replace `my-cluster` with a meaningful name for the cluster. This value appears in Prowler Cloud reports and helps identify the source of findings. See the `--cluster-name` flag documentation in [Getting Started with Kubernetes](/user-guide/providers/kubernetes/getting-started-k8s) for more details. ### Customizing the Schedule The `schedule` field uses standard cron syntax. Common examples: * `"0 2 * * *"` — daily at 02:00 UTC * `"0 */6 * * *"` — every 6 hours * `"0 2 * * 1"` — weekly on Mondays at 02:00 UTC ### Scanning Specific Namespaces To limit the scan to specific namespaces, add the `--namespace` flag to the `args` array: ```yaml theme={null} args: - "kubernetes" - "--push-to-cloud" - "--namespace" - "production,staging" ``` ## Step 4: Deploy and Verify Apply the CronJob to the cluster: ```console theme={null} kubectl apply -f prowler-cronjob.yaml ``` To trigger an immediate test run without waiting for the schedule: ```console theme={null} kubectl create job prowler-test-run --from=cronjob/prowler-k8s-scan -n prowler-ns ``` Monitor the job execution: ```console theme={null} kubectl get pods -n prowler-ns -l app=prowler --watch ``` Check the logs to confirm findings were pushed successfully: ```console theme={null} kubectl logs -n prowler-ns -l app=prowler --tail=50 ``` A successful upload produces output similar to: ``` Pushing findings to Prowler Cloud, please wait... Findings successfully pushed to Prowler Cloud. Ingestion job: fa8bc8c5-4925-46a0-9fe0-f6575905e094 See more details here: https://cloud.prowler.com/scans ``` ## Step 5: View Findings in Prowler Cloud Once the job completes and findings are pushed: 1. Navigate to [Prowler Cloud](https://cloud.prowler.com/) 2. Open the "Scans" section to verify the ingestion job status 3. Browse findings under the Kubernetes provider For details on the ingestion workflow and status tracking, refer to the [Import Findings](/user-guide/tutorials/prowler-import-findings) documentation. ## Tips and Troubleshooting * **Resource limits**: For large clusters, consider setting `resources.requests` and `resources.limits` on the container to prevent the scan from consuming excessive cluster resources. * **Network policies**: Ensure the Prowler pod can reach `api.prowler.com` over HTTPS (port 443). Adjust NetworkPolicies or egress rules if needed. * **Job history**: Kubernetes retains completed and failed jobs by default. Set `successfulJobsHistoryLimit` and `failedJobsHistoryLimit` in the CronJob spec to control cleanup: ```yaml theme={null} spec: successfulJobsHistoryLimit: 3 failedJobsHistoryLimit: 1 ``` * **API key rotation**: When rotating the API key, update the Secret and restart any running jobs: ```console theme={null} kubectl delete secret prowler-cloud-api-key -n prowler-ns kubectl create secret generic prowler-cloud-api-key \ --from-literal=api-key=pk_new_api_key_here \ --namespace prowler-ns ``` * **Failed uploads**: If the push to Prowler Cloud fails, the scan still completes and findings are saved locally in the container. Check the [Import Findings troubleshooting section](/user-guide/tutorials/prowler-import-findings#troubleshooting) for common error messages. # Visualize Multi-Cloud CIS Benchmarks With Power BI Source: https://docs.prowler.com/user-guide/cookbooks/powerbi-cis-benchmarks Ingest Prowler compliance CSV exports into a ready-made Microsoft Power BI template that surfaces CIS Benchmark posture across AWS, Azure, Google Cloud, and Kubernetes. The Multi-Cloud CIS Benchmarks Power BI template turns Prowler compliance CSV exports into an interactive dashboard. The template ingests scan results from Prowler CLI or Prowler Cloud and renders cross-provider CIS Benchmark coverage, profile-level breakdowns, regional drill-downs, and time-series trends. Center for Internet Security (CIS) Benchmarks are industry-standard configuration baselines maintained by CIS. The template and its source files live in the Prowler repository under [`contrib/PowerBI/Multicloud CIS Benchmarks`](https://github.com/prowler-cloud/prowler/tree/master/contrib/PowerBI/Multicloud%20CIS%20Benchmarks). ![Multi-Cloud CIS Benchmarks Power BI report cover showing aggregated compliance posture across providers](https://mintcdn.com/prowler/O48zT9POQ9mtz-C7/images/powerbi/report-cover.png?fit=max\&auto=format\&n=O48zT9POQ9mtz-C7\&q=85\&s=862ae33ed5427777372cb6795decb796) ## Prerequisites The setup requires the following components: * **Microsoft Power BI Desktop:** free download from Microsoft. * **Prowler compliance CSV exports:** produced by Prowler CLI or downloaded from Prowler Cloud or Prowler Local Server. * **Local directory:** holds the CSV exports that the template ingests at load time. ## Supported CIS Benchmarks The template ships with predefined mappings for the following CIS Benchmark versions. Exports must match these versions for the dashboard to populate correctly: | Compliance Framework | Version | | - | - | | CIS Amazon Web Services Foundations Benchmark | v6.0 | | CIS Microsoft Azure Foundations Benchmark | v5.0 | | CIS Google Cloud Platform Foundation Benchmark | v4.0 | | CIS Kubernetes Benchmark | v1.12.0 | > [!WARNING] > > Other CIS Benchmark versions are not recognized by the template. Confirm the framework version before running the scan or downloading the export. ## Setup ### Step 1: Install Microsoft Power BI Desktop Download and install Microsoft Power BI Desktop from the official Microsoft site. The template is opened with this application. ### Step 2: Generate Compliance CSV Exports Compliance CSV exports can be generated through Prowler CLI or downloaded from Prowler Cloud and Prowler Local Server. #### Option A: Prowler CLI Run a scan with the `--compliance` flag pointing to the appropriate CIS framework, for example: ```sh theme={null} prowler aws --compliance cis_6.0_aws prowler azure --compliance cis_5.0_azure prowler gcp --compliance cis_4.0_gcp prowler kubernetes --compliance cis_1.12_kubernetes ``` The compliance CSV exports are written to `output/compliance/` by default. #### Option B: Prowler Cloud or Prowler Local Server Open the Compliance section, select the desired CIS Benchmark, and download the CSV export. ![Compliance section in Prowler Cloud showing the CSV download option for a CIS Benchmark scan](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/powerbi/download-compliance-scan.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=dab986a26f8152f6ef22acdfd19a45c0) ### Step 3: Create a Local Directory for the Exports Place every CSV export in a single local directory. The template parses filenames to detect the provider, so filenames must keep the provider keyword (`aws`, `azure`, `gcp`, or `kubernetes`). > [!NOTE] > > Time-series visualizations such as "Compliance Percent Over Time" require multiple scans from different dates in the same directory. ### Step 4: Open the Power BI Template Download the template file [`Prowler Multicloud CIS Benchmarks.pbit`](https://github.com/prowler-cloud/prowler/raw/master/contrib/PowerBI/Multicloud%20CIS%20Benchmarks/Prowler%20Multicloud%20CIS%20Benchmarks.pbit) and open it. Power BI Desktop prompts for the full filepath to the directory created in step 3. ### Step 5: Provide the Directory Filepath Enter the absolute filepath without quotation marks. The Windows "copy as path" feature wraps the path in quotation marks automatically; remove them before submitting. ### Step 6: Save the Report as a `.pbix` File Once the filepath is submitted, the template ingests the CSV exports and renders the report. Save the populated report as a `.pbix` file for future use. Re-running the `.pbit` template generates a fresh report against an updated directory. ## Validation To confirm the CSV exports were ingested correctly, open the "Configuration" tab inside the report. ![Configuration tab in the Power BI report displaying loaded CIS Benchmarks, the Prowler CSV folder path, and the list of ingested exports](https://mintcdn.com/prowler/O48zT9POQ9mtz-C7/images/powerbi/validation.png?fit=max\&auto=format\&n=O48zT9POQ9mtz-C7\&q=85\&s=11a7544fba92dd7dbf266d5e062dc28c) The "Configuration" tab exposes three tables: * **Loaded CIS Benchmarks:** lists the benchmarks and versions supported by the template. This table is defined by the template itself and is not editable. All benchmarks remain listed regardless of which provider exports were supplied. * **Prowler CSV Folder:** displays the absolute path provided during template load. * **Loaded Prowler Exports:** lists every CSV file detected in the directory. A green checkmark identifies the file used as the latest assessment for each provider and benchmark combination. ## Report Sections The report is organized into three navigable pages: | Report Page | Purpose | | - | - | | Overview | Aggregates CIS Benchmark posture across AWS, Azure, Google Cloud, and Kubernetes. | | Benchmark | Focuses on a single CIS Benchmark with profile-level and regional filters. | | Requirement | Drill-through page that surfaces details for a single benchmark requirement. | ### Overview Page The Overview page summarizes CIS Benchmark posture across every supported provider. ![Overview page in the Power BI report aggregating CIS Benchmark posture across AWS, Azure, Google Cloud, and Kubernetes](https://mintcdn.com/prowler/O48zT9POQ9mtz-C7/images/powerbi/overview-page.png?fit=max\&auto=format\&n=O48zT9POQ9mtz-C7\&q=85\&s=94b9884dad969dea9fc5f009e135ac45) The Overview page contains the following components: | Component | Description | | - | - | | CIS Benchmark Overview | Table listing benchmark name, version, and overall compliance percentage. | | Provider by Requirement Status | Bar chart breaking down requirements by status and provider. | | Compliance Percent Heatmap | Heatmap of compliance percentage by benchmark and profile level. | | Profile Level by Requirement Status | Bar chart breaking down requirements by status and profile level. | | Compliance Percent Over Time by Provider | Line chart tracking overall compliance percentage over time by provider. | ### Benchmark Page The Benchmark page focuses on a single CIS Benchmark. The benchmark, profile level, and region can be selected through dropdown filters. ![Benchmark page in the Power BI report showing region heatmap, section breakdown, time-series trend, and the requirements table](https://mintcdn.com/prowler/O48zT9POQ9mtz-C7/images/powerbi/benchmark-page.png?fit=max\&auto=format\&n=O48zT9POQ9mtz-C7\&q=85\&s=3a098e0729deeb0c8fc303501336ac30) The Benchmark page contains the following components: | Component | Description | | - | - | | Compliance Percent Heatmap | Heatmap of compliance percentage by region and profile level. | | Benchmark Section by Requirement Status | Bar chart of requirements grouped by benchmark section and status. | | Compliance Percent Over Time by Region | Line chart tracking compliance percentage over time by region. | | Benchmark Requirements | Table listing requirement section, requirement number, requirement title, number of resources tested, status, and failing checks. | ### Requirement Page The Requirement page is a drill-through view that exposes the full context of a single requirement. To populate the page, right-click a row in the "Benchmark Requirements" table on the Benchmark page and select "Drill through" > "Requirement". ![Requirement drill-through page in the Power BI report showing rationale, remediation, regional breakdown, and the resource-level check results](https://mintcdn.com/prowler/O48zT9POQ9mtz-C7/images/powerbi/requirement-page.png?fit=max\&auto=format\&n=O48zT9POQ9mtz-C7\&q=85\&s=daef90a4405ff4432022824bc6041b1d) The Requirement page contains the following components: | Component | Description | | - | - | | Title | Requirement title. | | Rationale | Rationale for the requirement. | | Remediation | Remediation guidance for the requirement. | | Region by Check Status | Bar chart of Prowler check results grouped by region and status. | | Resource Checks for Benchmark Requirements | Table listing resource ID, resource name, status, description, and the underlying Prowler check. | ## Walkthrough Video A full walkthrough is available on YouTube: [![Multi-Cloud CIS Benchmarks Power BI walkthrough video thumbnail](https://mintcdn.com/prowler/O48zT9POQ9mtz-C7/images/powerbi/walkthrough-video-thumb.png?fit=max\&auto=format\&n=O48zT9POQ9mtz-C7\&q=85\&s=e4ad5d29e2886d90eadc374165cd9cab)](https://www.youtube.com/watch?v=lfKFkTqBxjU) ## Related Resources > [card] [Compliance Frameworks](/user-guide/compliance/tutorials/compliance) > > Review the Compliance workflow across Prowler Cloud, Prowler Local Server, and Prowler CLI. > [card] [Prowler Dashboard](/user-guide/cli/tutorials/dashboard) > > Explore the built-in local dashboard for Prowler CSV exports. # Organizations Across Cloud Providers Source: https://docs.prowler.com/user-guide/organizations Understand organization hierarchies and onboarding across AWS, Google Cloud, and Azure Cloud providers use organization-level hierarchies to group accounts, projects, or subscriptions and apply access and governance consistently. Prowler uses these hierarchies to discover cloud targets and help configure multi-account or multi-project scanning. This guide explains the shared lifecycle and the differences between AWS Organizations, Google Cloud organizations, and Azure Management Groups. Use the provider-specific guides for commands, permissions, and limitations. ## Organization Lifecycle Organization-level onboarding generally follows these steps: 1. **Identify the hierarchy:** Locate the organization, management account, management group, folder, organizational unit, or equivalent parent node in the cloud provider. 2. **Grant access:** Assign the provider permissions required to enumerate the hierarchy and read the resources that Prowler scans. 3. **Discover members:** Use Prowler to retrieve accounts, projects, or subscriptions under the selected hierarchy. 4. **Select scan targets:** Choose the cloud targets to connect or scan. Discovery does not necessarily make every discovered target a Prowler provider. 5. **Test access:** Confirm that Prowler can authenticate to each selected target and read its resources. 6. **Scan and maintain:** Run scans, review findings, and repeat discovery when the provider hierarchy changes. > [!NOTE] > > Organization membership changes are not automatically synchronized in every Prowler workflow. Follow the provider-specific guide to learn when manual rediscovery is required. ## Capability Matrix | Capability | AWS Organizations | Google Cloud organization | Azure Management Groups | | - | - | - | - | | Hierarchy members | AWS accounts grouped in organizational units (OUs) | Projects grouped in folders and nested folders | Subscriptions grouped in management groups | | Organization-level discovery | Supported through AWS Organizations APIs | Supported through the Cloud Asset API | Supported through Azure management-group and subscription APIs | | Primary scan target | AWS account | Google Cloud project | Azure subscription | | Common organization-level permission | IAM role in the management or delegated administrator account | Cloud Asset Viewer or Cloud Asset Owner at the organization node | Appropriate Azure role assignment at the management-group or subscription scope | | Provider-specific onboarding | AWS account discovery and optional StackSet role deployment | Project discovery under an organization ID | Subscription discovery under a management group; role assignments inherit to subscriptions | | Membership maintenance | Repeat the discovery flow when accounts are added or removed | Re-run organization discovery when projects or folders change | Refresh discovery when subscriptions move between management groups | ## Provider Guides ### AWS Organizations The [AWS Organizations guide](/user-guide/providers/aws/organizations) covers account details, delegated administration, IAM roles, CloudFormation StackSets, and CLI scanning. For Prowler Cloud onboarding, see [AWS Organizations in Prowler Cloud](/user-guide/tutorials/prowler-cloud-aws-organizations). ### Google Cloud Organization The [Google Cloud organization guide](/user-guide/providers/gcp/organization) covers scanning projects under an organization ID, organization-level permissions, and Cloud Asset API requirements. For Prowler Cloud onboarding, see [Google Cloud organizations in Prowler Cloud](/user-guide/tutorials/prowler-cloud-gcp-organizations). ### Azure Management Groups The [Azure Management Groups guide](/user-guide/providers/azure/management-groups) covers hierarchy setup, role assignment, subscription scope, and Azure-specific limitations. For Prowler Cloud onboarding, see [Azure Management Groups in Prowler Cloud](/user-guide/tutorials/prowler-cloud-azure-management-groups). ## Scope Boundaries The organization concepts in this guide refer only to cloud-provider resource hierarchies: * **GitHub organizations** group repositories and GitHub resources. They are a separate provider concept and are not part of AWS, Google Cloud, or Azure organization discovery. * **MongoDB Atlas organizations** group Atlas projects and teams. They use a separate provider API and authentication model. * **Prowler Cloud organizations** are internal tenants that isolate providers, scans, findings, users, and permissions. They are not the same as a cloud-provider organization and do not replace one. Choose the guide that matches the hierarchy being configured, then use the relevant Prowler Cloud or CLI workflow for the scan targets. # Alibaba Cloud Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/alibabacloud/authentication Prowler supports multiple Alibaba Cloud authentication flows. If more than one is configured at the same time, the provider resolves them in this order: 1. **Credentials URI** 2. **OIDC Role Authentication** 3. **ECS RAM Role** 4. **RAM Role Assumption** 5. **STS Temporary Credentials** 6. **Permanent Access Keys** 7. **Default Credential Chain** > [!WARNING] > > Do not use the AccessKey pair of the main Alibaba Cloud account for Prowler. Use a RAM user, a RAM role, or another temporary credential flow instead. ## Choose The Right Method | Where Prowler runs | What you need to create | Recommended method | | - | - | - | | Local workstation | RAM user + AccessKey pair | [RAM User And AccessKey](#ram-user-and-accesskey) | | CI runner outside Alibaba Cloud | RAM user + AccessKey pair, optionally a target RAM role | [RAM Role Assumption](#ram-role-assumption-recommended) | | ECS instance | ECS RAM role attached to the instance | [ECS RAM Role](#ecs-ram-role) | | ACK / Kubernetes | OIDC IdP + RAM role + OIDC token file | [OIDC Role Authentication](#oidc-role-authentication) | | Internal credential broker | An HTTP endpoint that returns STS credentials | [Credentials URI](#credentials-uri) | ## RAM User And AccessKey This is the simplest setup for a workstation or a basic CI runner. ### Create The RAM User 1. Open the [RAM console](https://ram.console.alibabacloud.com/). 2. Go to `Identities` > `Users`. 3. Click `Create User`. 4. Enter a logon name and display name. 5. In `Access Configuration`, select `Permanent AccessKey`. ![Create a RAM user and enable Permanent AccessKey](https://mintcdn.com/prowler/CMbAMi4-WUTqMM9m/user-guide/providers/alibabacloud/img/create_user.png?fit=max\&auto=format\&n=CMbAMi4-WUTqMM9m\&q=85\&s=211f44d0e70fd22534d9dbfb713f98c1) 6. Save the generated `AccessKey ID` and `AccessKey Secret` immediately. Alibaba Cloud only shows the secret once. 7. Grant the user the read permissions required for the Alibaba Cloud services you want Prowler to scan. ![Grant permissions to the RAM user](https://mintcdn.com/prowler/CMbAMi4-WUTqMM9m/user-guide/providers/alibabacloud/img/grant_permissions.png?fit=max\&auto=format\&n=CMbAMi4-WUTqMM9m\&q=85\&s=c7a94c680edfe0d299f853e6c0b34e81) Alibaba Cloud walkthroughs with current console screenshots: * [Create a RAM user](https://www.alibabacloud.com/help/en/ram/user-guide/create-a-ram-user) * [Create an AccessKey pair](https://www.alibabacloud.com/help/en/ram/user-guide/create-an-accesskey-pair) * [Grant permissions to a RAM user](https://www.alibabacloud.com/help/en/ram/user-guide/grant-permissions-to-the-ram-user) ### Use The AccessKey With Prowler ```bash theme={null} export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret" prowler alibabacloud ``` Prowler also accepts `ALIYUN_ACCESS_KEY_ID` and `ALIYUN_ACCESS_KEY_SECRET` for compatibility, but `ALIBABA_CLOUD_*` is the preferred naming. ### Use The Default Credential Chain If you prefer not to export credentials in every shell, you can store them with the Alibaba Cloud CLI and let Prowler reuse the default credential chain from `~/.aliyun/config.json`. ```bash theme={null} aliyun configure --mode AK prowler alibabacloud ``` For profile management details, see Alibaba Cloud's [CLI credential management guide](https://www.alibabacloud.com/help/en/cli/other-configure-command-operations). ## RAM Role Assumption (Recommended) Use this when: * you want short-lived credentials instead of long-lived AccessKeys in Prowler, * you are scanning another Alibaba Cloud account, or * you are configuring Alibaba Cloud in Prowler Cloud and want to provide a `Role ARN`. This flow has two parts: 1. A source identity that can call `sts:AssumeRole`. 2. A target RAM role that has the scan permissions. ### Create The Source Identity Create a RAM user with an AccessKey pair by following the steps in [RAM User And AccessKey](#ram-user-and-accesskey), or reuse an existing automation identity. ### Create The Target Role 1. Open the [RAM console](https://ram.console.alibabacloud.com/). 2. Go to `Identities` > `Roles`. 3. Click `Create Role`. 4. Set `Principal Type` to `Cloud Account`. 5. Choose: * `Current Account` if the RAM user and the role are in the same account. * `Other Account` if the RAM user belongs to a different Alibaba Cloud account. 6. Give the role a name such as `ProwlerAuditRole`. 7. Attach the scan permissions to the role. 8. Copy the role ARN in the format `acs:ram:::role/`. If you want to restrict the role so that only one RAM user or one RAM role can assume it, edit the trust policy accordingly. Helpful references: * [Create a RAM role for a trusted Alibaba Cloud account](https://www.alibabacloud.com/help/en/ram/user-guide/create-a-ram-role-for-a-trusted-alibaba-cloud-account) * [Assume a RAM role](https://www.alibabacloud.com/help/doc-detail/116820.html) ### Allow The Source Identity To Assume The Role The source RAM user must be able to call `sts:AssumeRole`. The easiest starting point is to attach Alibaba Cloud's `AliyunSTSAssumeRoleAccess` policy to that RAM user. If you want tighter scope, attach a custom policy limited to the target role ARN. ### Run Prowler ```bash theme={null} export ALIBABA_CLOUD_ACCESS_KEY_ID="source-user-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="source-user-access-key-secret" prowler alibabacloud \ --role-arn acs:ram::123456789012:role/ProwlerAuditRole \ --role-session-name ProwlerAssessmentSession ``` You can also set the role ARN with `ALIBABA_CLOUD_ROLE_ARN`, but the source AccessKey pair is still required for this flow. ## STS Temporary Credentials Use this if another tool already gives you a temporary `AccessKey ID`, `AccessKey Secret`, and `SecurityToken`. This is common when: * a CI platform brokers Alibaba credentials for the job, * your internal tooling already calls `AssumeRole`, or * you want to test with a short-lived session before switching to a RAM role flow. ```bash theme={null} export ALIBABA_CLOUD_ACCESS_KEY_ID="your-sts-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-sts-access-key-secret" export ALIBABA_CLOUD_SECURITY_TOKEN="your-sts-security-token" prowler alibabacloud ``` You can also store the session in the Alibaba CLI configuration: ```bash theme={null} aliyun configure --mode StsToken prowler alibabacloud ``` > [!NOTE] > > Prowler does not mint standalone STS sessions for you. If you use this method, you must provide all three STS values from your external workflow. ## ECS RAM Role Use this when Prowler runs on an ECS instance and you do not want to store any AccessKeys on disk. ### Create And Attach The Role 1. Open the [RAM console](https://ram.console.alibabacloud.com/). 2. Go to `Identities` > `Roles`. 3. Click `Create Role`. 4. Set the trusted entity to `Alibaba Cloud Service`. 5. Select `ECS` as the trusted service. 6. Attach the read permissions required for the scan. 7. Attach that RAM role to the ECS instance that runs Prowler. Alibaba Cloud guide: * [Instance RAM roles](https://www.alibabacloud.com/help/en/doc-detail/54579.html) ### Run Prowler ```bash theme={null} prowler alibabacloud --ecs-ram-role ProwlerEcsRole ``` Or: ```bash theme={null} export ALIBABA_CLOUD_ECS_METADATA="ProwlerEcsRole" prowler alibabacloud ``` ## OIDC Role Authentication Use this when Prowler runs in ACK or another Kubernetes environment that provides an OIDC token file. ### Create The OIDC Identity Provider 1. Open the [RAM console](https://ram.console.alibabacloud.com/). 2. Go to `Integrations` > `SSO`. 3. Select `Role-based SSO`, then the `OIDC` tab. 4. Click `Create IdP`. 5. Fill in: * `IdP Name` * `Issuer URL` * `Fingerprint` * `Client ID` 6. Create the IdP and note its ARN. Alibaba Cloud guides: * [Manage an OIDC IdP](https://www.alibabacloud.com/help/en/ram/manage-an-oidc-idp) * [Overview of role-based OIDC SSO](https://www.alibabacloud.com/help/en/ram/overview-of-oidc-based-sso) ### Create The RAM Role Trusted By That IdP Create a RAM role whose trusted entity is the OIDC IdP, then attach the scan permissions to that role. If you are running in ACK with RRSA, this is typically the role bound to the service account that runs Prowler. ### Provide The OIDC Variables To Prowler Prowler currently expects: * `--oidc-role-arn` for the RAM role ARN, * `ALIBABA_CLOUD_OIDC_PROVIDER_ARN` for the OIDC provider ARN, * `ALIBABA_CLOUD_OIDC_TOKEN_FILE` for the token file path. Example: ```bash theme={null} export ALIBABA_CLOUD_OIDC_PROVIDER_ARN="acs:ram::123456789012:oidc-provider/ack-rrsa-provider" export ALIBABA_CLOUD_OIDC_TOKEN_FILE="/var/run/secrets/ack.alibabacloud.com/rrsa-tokens/token" prowler alibabacloud --oidc-role-arn acs:ram::123456789012:role/ProwlerAckRole ``` If you use ACK RRSA, Alibaba's `ack-pod-identity-webhook` can inject the three required environment variables and mount the token file into the pod automatically: * [ack-pod-identity-webhook](https://www.alibabacloud.com/help/en/cs/user-guide/ack-pod-identity-webhook) * [Use RRSA to authorize different pods to access different cloud services](https://www.alibabacloud.com/help/doc-detail/356611.html) > [!NOTE] > > Even if your pod already exposes `ALIBABA_CLOUD_ROLE_ARN`, use `--oidc-role-arn` with Prowler. The provider currently reads the role ARN for OIDC from the CLI argument. ## Credentials URI Use this only if you already operate an internal credential broker that returns temporary Alibaba Cloud credentials over HTTP. The endpoint must return a JSON body with this structure: ```json theme={null} { "Code": "Success", "AccessKeyId": "STS.xxxxx", "AccessKeySecret": "xxxxx", "SecurityToken": "xxxxx", "Expiration": "2026-04-23T10:00:00Z" } ``` Run Prowler with: ```bash theme={null} prowler alibabacloud --credentials-uri http://localhost:8080/credentials ``` Or: ```bash theme={null} export ALIBABA_CLOUD_CREDENTIALS_URI="http://localhost:8080/credentials" prowler alibabacloud ``` For the expected response format, see Alibaba Cloud's SDK guide for [URI credentials](https://www.alibabacloud.com/help/en/sdk/developer-reference/v2-manage-access-credentials). ## Permissions Guidance The exact minimum policy depends on the checks and services you enable. If you are using the RAM console's `Grant Permission` screen, search for the **system policy names** below. Alibaba Cloud often uses product policy names that differ from the service name shown in Prowler. ### System Policies In The RAM Console | Prowler use case | Policy name in RAM console | Notes | | - | - | - | | Source user for `--role-arn` | `AliyunSTSAssumeRoleAccess` | Grants `sts:AssumeRole` so the source identity can assume the scan role. | | RAM checks | `AliyunRAMReadOnlyAccess` | Covers RAM read APIs such as users, groups, policies, MFA devices, and account alias. | | ECS checks | `AliyunECSReadOnlyAccess` | Read-only ECS access. | | VPC checks | `AliyunVPCReadOnlyAccess` | Read-only VPC access. | | OSS checks | `AliyunOSSReadOnlyAccess` | Read-only OSS access. | | ActionTrail checks | `AliyunActionTrailReadOnlyAccess` | Read-only ActionTrail access. | | SLS checks | `AliyunLogReadOnlyAccess` | In the RAM console, Simple Log Service appears as `Log`. | | RDS checks | `AliyunRDSReadOnlyAccess` | Read-only RDS access. | | ACK / Container Service checks | `AliyunCSReadOnlyAccess` | In the RAM console, ACK permissions appear under `CS`. | | Security Center checks | `AliyunYundunSASReadOnlyAccess` | In the RAM console, Security Center appears under `Yundun SAS`. | ### Recommended Starting Point For a broad Alibaba Cloud scan, the identity used by Prowler usually needs read access to the services Prowler currently audits, including: * `RAM` * `ECS` * `VPC` * `OSS` * `ActionTrail` * `Simple Log Service (SLS)` * `RDS` * `Container Service / ACK` * `Security Center` Use the following setup as a practical starting point: * If you use **static AccessKeys**, attach the read-only policies above directly to the RAM user used by Prowler. * If you use **RAM role assumption**, attach `AliyunSTSAssumeRoleAccess` to the source RAM user and attach the read-only policies above to the target scan role. * If you use **ECS RAM role** or **OIDC/RRSA**, attach the read-only policies above to the role assumed by Prowler. If you prefer a tighter custom policy instead of system policies, the current provider relies on read APIs such as: * `ram:Get*`, `ram:List*` * `ecs:Describe*` * `vpc:Describe*` * `oss:Get*`, `oss:List*` * `actiontrail:Describe*` * `log:Get*`, `log:List*`, `log:Query*` * `rds:Describe*` * `cs:Get*`, `cs:List*`, `cs:Describe*` * `yundun-sas:Get*`, `yundun-sas:Describe*`, `yundun-sas:List*` > [!NOTE] > > If a service is denied, Prowler can still start, but checks for that service may fail or return incomplete results. # Getting Started With Alibaba Cloud on Prowler Source: https://docs.prowler.com/user-guide/providers/alibabacloud/getting-started-alibabacloud Prowler supports Alibaba Cloud both from the CLI and from Prowler Cloud. This guide walks you through the requirements, how to connect the provider in the UI, and how to run scans from the command line. ## Prerequisites Before you begin, make sure you have: 1. An **Alibaba Cloud Account ID** (visible in the Alibaba Cloud Console under your profile). 2. **Credentials** with appropriate permissions: * **RAM User with Access Keys**: For local CLI usage or simple CI setups. See [RAM User and AccessKey](/user-guide/providers/alibabacloud/authentication#ram-user-and-accesskey). * **RAM Role**: For role assumption and Prowler Cloud onboarding. See [RAM Role Assumption](/user-guide/providers/alibabacloud/authentication#ram-role-assumption-recommended). 3. The required permissions for Prowler to audit your resources. See the [Alibaba Cloud Authentication](/user-guide/providers/alibabacloud/authentication) guide for setup steps and permission guidance. > [card] [Prowler Cloud](#prowler-cloud) > > Onboard Alibaba Cloud using Prowler Cloud > [card] [Prowler CLI](#prowler-cli) > > Onboard Alibaba Cloud using Prowler CLI ## Prowler Cloud [Added in:  5.18.0](https://github.com/prowler-cloud/prowler/releases/tag/5.18.0) > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Step 1: Get Your Alibaba Cloud Account ID 1. Log in to the [Alibaba Cloud Console](https://home.console.alibabacloud.com/) 2. Click your profile avatar in the top-right corner 3. Locate and copy your Account ID ![Get Account ID](https://mintcdn.com/prowler/mhRcL74qR-qVhTTv/images/providers/alibaba-account-id.png?fit=max\&auto=format\&n=mhRcL74qR-qVhTTv\&q=85\&s=f9c886f044c3281d82c836891ffbd0c4) ### Step 2: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Go to "Configuration" > "Providers" ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider" ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Alibaba Cloud" ![Select Alibaba Cloud](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-alibaba-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=89ddb25415e60a446f382375ac9f7e4b) 5. Enter your Alibaba Cloud Account ID and optionally provide a friendly alias ![Add Account ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-alibaba-account-id.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=e83040b4f5c75d615456fce6e2f2f344) ### Step 3: Choose and Provide Authentication After the Account ID is in place, select the authentication method that matches your Alibaba Cloud setup: ![Select Auth Method](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-auth-method-alibaba.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aef36946bb6ea8c2468555ea87d6cf4b) #### RAM Role Assumption (Recommended) Use this method for secure cross-account access. For detailed instructions on how to create the RAM role, see the [Authentication guide](/user-guide/providers/alibabacloud/authentication#ram-role-assumption-recommended). 1. Enter the **Role ARN** (format: `acs:ram:::role/`) 2. Enter the **Access Key ID** and **Access Key Secret** of the RAM user that will assume the role ![Input the Role ARN](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/alibaba-get-role-arn.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=3bcf2cd532c96bef1510834a6740b459) > [!NOTE] > > The RAM user whose credentials you provide must have permission to assume the target role. For more details, see the [Alibaba Cloud AssumeRole API documentation](https://www.alibabacloud.com/help/en/ram/developer-reference/api-sts-2015-04-01-assumerole). #### Credentials (Static Access Keys) Use static credentials for quick scans (not recommended for production). For detailed setup, see the [Authentication guide](/user-guide/providers/alibabacloud/authentication#ram-user-and-accesskey). 1. Enter the **Access Key ID** and **Access Key Secret** ![Filled Credentials Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/alibaba-credentials-form.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=c05c5eceaa3651e8db30b3fd65b05d75) > [!WARNING] > > Static access keys are long-lived credentials. For production environments, consider using RAM Role Assumption instead. ### Step 4: Launch the Scan 1. Click "Next" to review your configuration 2. Click "Launch Scan" to start auditing your Alibaba Cloud account ![Launch Scan](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/launch-scan-alibaba.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=3d15b66291b945c3077f739850c23f71) *** ## Prowler CLI [Added in:  5.15.0](https://github.com/prowler-cloud/prowler/releases/tag/5.15.0) You can also run Alibaba Cloud assessments directly from the CLI. Both command-line flags and environment variables are supported. ### Step 1: Select an Authentication Method Choose one of the following authentication methods. For step-by-step credential creation and the full list of supported authentication modes, see the [Authentication guide](/user-guide/providers/alibabacloud/authentication). #### Environment Variables ```bash theme={null} export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret" prowler alibabacloud ``` #### Default Credential Chain ```bash theme={null} aliyun configure --mode AK prowler alibabacloud ``` #### RAM Role Assumption ```bash theme={null} # Using --role-arn CLI flag export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret" prowler alibabacloud --role-arn acs:ram::123456789012:role/ProwlerAuditRole # Or using environment variables export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret" export ALIBABA_CLOUD_ROLE_ARN="acs:ram::123456789012:role/ProwlerAuditRole" prowler alibabacloud ``` #### ECS RAM Role (for ECS instances) ```bash theme={null} prowler alibabacloud --ecs-ram-role RoleName ``` ### Step 2: Run the First Scan #### Scan All Regions ```bash theme={null} prowler alibabacloud ``` #### Scan Specific Regions ```bash theme={null} prowler alibabacloud --region cn-hangzhou cn-shanghai ``` #### Run Specific Checks ```bash theme={null} prowler alibabacloud --checks ram_no_root_access_key ram_user_mfa_enabled_console_access ``` #### Run a Compliance Framework ```bash theme={null} prowler alibabacloud --compliance cis_2.0_alibabacloud ``` ### Additional Tips * Combine flags (for example, `--checks` or `--services`) just like with other providers. * Use `--output-modes` to export findings in JSON, CSV, ASFF, etc. * For more authentication options (OIDC, Credentials URI, STS), see the [Authentication guide](/user-guide/providers/alibabacloud/authentication). # AWS Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/aws/authentication Prowler requires AWS credentials to function properly. Authentication is available through the following methods: * Static Credentials * Assumed Role When using **Assumed Role**, the Prowler UI exposes two credential sources for calling `sts:AssumeRole`. The labels differ between Prowler Cloud and Prowler Local Server, but both map to the same underlying credential types: * **AWS SDK Default** (shown as *"Prowler Cloud will assume your IAM role"* in Prowler Cloud and *"AWS SDK Default"* in Prowler Local Server): Prowler uses the credentials already available to the API and worker containers through the [AWS SDK default credential chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). This is the default in Prowler Cloud and requires extra configuration in Prowler Local Server (see [Configuring AWS SDK Default for Prowler Local Server](#configuring-aws-sdk-default-for-prowler-local-server)). * **Access & Secret Key**: You paste an IAM user's `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN` into the form. Prowler uses those keys to call `sts:AssumeRole`. ## Required Permissions To ensure full functionality, attach the following AWS managed policies to the designated user or role: * `arn:aws:iam::aws:policy/SecurityAudit` * `arn:aws:iam::aws:policy/job-function/ViewOnlyAccess` ### Additional Permissions For certain checks, additional read-only permissions are required. Attach the following custom policy to your role: [prowler-additions-policy.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-additions-policy.json) ## Assume Role (Recommended) This method grants permanent access and is the recommended setup for production environments. > [tab] CloudFormation > > 1. Download the [Prowler Scan Role Template](https://raw.githubusercontent.com/prowler-cloud/prowler/refs/heads/master/permissions/templates/cloudformation/prowler-scan-role.yml) > > ![Prowler Scan Role Template](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/prowler-scan-role-template.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=1edf1caeb3cfd336a65d6bb59a48e5dc) > > ![Download Role Template](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/download-role-template.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=b2ac197fa1a12dd7003b26fbc31e9008) > > 2. Open the [AWS Console](https://console.aws.amazon.com), search for **CloudFormation** > > ![CloudFormation Search](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/cloudformation-nav.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=13596ccb401e7cd768733a0df90af8b4) > > 3. Go to **Stacks** and click "Create stack" > "With new resources (standard)" > > ![Create Stack](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/create-stack.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=b8b2a25dc47c27ca8d9a8ab9f6db3ab0) > > 4. In **Specify Template**, choose "Upload a template file" and select the downloaded file > > ![Upload a template file](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/upload-template-file.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=cc2171a89e6a80ea42dae39fe025d0ce) > > ![Upload file from downloads](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/upload-template-from-downloads.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=da46dfe45de14126e6e7ff654a988697) > > 5. Click "Next", provide a stack name and the **External ID** shown in the Prowler Cloud setup screen > > ![External ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/prowler-cloud-external-id.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=c34af20bca0d9cae591af9df152aef87) > > ![Stack Data](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/fill-stack-data.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=aea65d657787c8998f9dadd0469b3dbb) > > > [!NOTE] > > > > An **External ID** is required when assuming the *ProwlerScan* role to prevent the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). > > 6. Acknowledge the IAM resource creation warning and proceed > > ![Stack Creation Second Step](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/stack-creation-second-step.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=adb50400ace2594bd543ca8512599baf) > > 7. Click "Submit" to deploy the stack > > ![Click Submit](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/submit-third-page.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=bf904bbe52bd7cf77264645def7ce595) > [tab] Terraform > > To provision the scan role using Terraform: > > 1. Run the following commands: > > ```bash theme={null} > terraform init > terraform plan > terraform apply > ``` *** ## Configuring AWS SDK Default for Prowler Local Server When running Prowler Local Server with Docker Compose, the API and worker containers do not have AWS credentials by default. Selecting **AWS SDK Default** without configuring those credentials produces: ``` AWSAssumeRoleError[1012]: AWS assume role error - An error occurred (InvalidClientTokenId) when calling the AssumeRole operation: The security token included in the request is invalid. ``` To fix this, expose an IAM identity with `sts:AssumeRole` permission on the target role to both the `api` and `worker` services. ### Option 1: Environment Variables in `.env` Add the following keys to the `.env` file used by `docker-compose.yml`: ```bash theme={null} AWS_ACCESS_KEY_ID="" AWS_SECRET_ACCESS_KEY="" AWS_SESSION_TOKEN="" AWS_DEFAULT_REGION="us-east-1" ``` The existing `docker-compose.yml` already loads `.env` into the `api`, `worker`, and `worker-beat` services, so `boto3` will pick them up through the default credential chain. > [!WARNING] > > Treat the `.env` file as a secret. Do not commit it to version control, scope the IAM identity to the minimum permissions required (`sts:AssumeRole` on the target `ProwlerScan` role only), prefer short-lived credentials over long-lived access keys, and rotate the keys immediately if you suspect exposure. Recreate the containers to apply the change. A plain `docker compose restart` will **not** reload values from a modified `.env` file — you must force-recreate: ```bash theme={null} docker compose up -d --force-recreate api worker worker-beat ``` ### Option 2: IAM Role (Host with Instance Metadata) If you run Prowler Local Server on an EC2 instance, ECS task, or EKS pod with an attached IAM role that can assume the scan role, no extra configuration is needed — `boto3` resolves credentials through instance or task metadata automatically. ### Trust Policy: Align `IAMPrincipal` With Your Identity The [Prowler scan role CloudFormation template](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml) restricts the trust policy with: ``` aws:PrincipalArn StringLike arn:aws:iam::: ``` `IAMPrincipal` defaults to `role/prowler*`, which only allows IAM roles whose name starts with `prowler`. If the identity hosting the API and worker containers is anything else, the `sts:AssumeRole` call fails with `AccessDenied` even when the credentials themselves are valid. Redeploy (or update) the CloudFormation stack with an `IAMPrincipal` that matches your identity: | Your identity on the API/worker containers | `IAMPrincipal` value | | - | - | | IAM user (for example `prowler-app`) | `user/prowler-app` | | IAM role whose name doesn't start with `prowler` | `role/` | `AccountId` must also point to the account where that identity lives — the default is Prowler Cloud's account and only applies when assuming from Prowler Cloud. > [!NOTE] > > The same `External ID` entered in the Prowler UI must match the `ExternalId` parameter used when deploying the CloudFormation stack. A mismatch produces `AccessDenied` on `sts:AssumeRole`, not `InvalidClientTokenId`. *** ## Credentials > [tab] Long term credentials > > 1. Go to the [AWS Console](https://console.aws.amazon.com), open **CloudShell** > > ![AWS CloudShell](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/aws-cloudshell.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=a25bc51d28015c73a18299467a09abcf) > > 2. Run: > > ```bash theme={null} > aws iam create-access-key > ``` > [tab] Short term credentials (Recommended) > > Use the [AWS Access Portal](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html) or the CLI: > > 1. Retrieve short-term credentials for the IAM identity using this command: > > ```bash theme={null} > aws sts get-session-token --duration-seconds 900 > ``` > > > [!NOTE] > > > > Check the aws documentation [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/sts_example_sts_GetSessionToken_section.html) > > 2. Copy the output containing: > > * `AccessKeyId` > > * `SecretAccessKey` > > * `SessionToken` > > > Sample output: > > ```json theme={null} > { > "Credentials": { > "AccessKeyId": "ASIAIOSFODNN7EXAMPLE", > "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY", > "SessionToken": "AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtpZ3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE", > "Expiration": "2020-05-19T18:06:10+00:00" > } > } > ``` # Boto3 Retrier and Timeout Configuration in Prowler Source: https://docs.prowler.com/user-guide/providers/aws/boto3-configuration Prowler's AWS Provider leverages Boto3's [Standard](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html) retry mode to automatically retry client calls to AWS services when encountering errors or exceptions. ## Timeout Configuration [Added in:  5.42.0](https://github.com/prowler-cloud/prowler/releases/tag/5.42.0) Every AWS API call is bounded by two timeouts: * Connect timeout: seconds to wait to establish a connection (TCP, proxy tunnel and TLS handshake) to the AWS endpoint. Prowler's default is 10 seconds, configurable via `--aws-connect-timeout 5`. * Read timeout: seconds to wait for a response once connected. Prowler's default is 60 seconds, configurable via `--aws-read-timeout 30`. Both timeouts can also be set through environment variables, which is the way to tune them in Prowler Cloud and other deployments without a CLI: ```console theme={null} export PROWLER_AWS_BOTO3_CONNECT_TIMEOUT=5 export PROWLER_AWS_BOTO3_READ_TIMEOUT=30 ``` CLI flags take precedence over the environment variables. Prowler sets both timeouts explicitly, so `AWS_DEFAULTS_MODE` and a `connect_timeout` in `~/.aws/config` are ignored; use the flag or the environment variable instead. > [!NOTE] > > Boto3 defaults both timeouts to 60 seconds. In networks with restricted egress (for example VPC endpoints for a subset of services, GovCloud or private deployments), every AWS service without a reachable endpoint used to cost up to 4 attempts × 60 seconds (the first call plus the 3 retries) for each region. Prowler lowers the connect timeout to 10 seconds so unreachable endpoints fail fast; lower it further together with `--aws-retries-max-attempts 0`, which disables retries and leaves a single attempt per call, if a scan still spends most of its time waiting on unreachable services. ## Retries Configuration [Added in:  5.44.0](https://github.com/prowler-cloud/prowler/releases/tag/5.44.0) The number of retries is set with `--aws-retries-max-attempts`, where `0` disables retries. It can also be set through an environment variable, which is the way to tune it in Prowler Cloud and other deployments without a CLI: ```console theme={null} export PROWLER_AWS_BOTO3_RETRIES_MAX_ATTEMPTS=0 ``` The CLI flag takes precedence over the environment variable. The value must be a non-negative integer; when neither is set, Prowler uses 3 retries. > [!WARNING] > > The environment variable is process-wide: it applies to every AWS provider built in the process where it is set, not only to a connection check. A scan started in that same process picks it up too. Boto3's Standard retry mode, which Prowler uses, also retries service-side throttling responses (see the errors listed below), so `0` disables retries for those as well. On a large account a scan can hit throttling under normal load, and with retries disabled that throttling becomes a hard failure instead of a retried call. Set the variable only on the processes that run connection checks; leave scan workers on the default, or raise their retry count instead of lowering it. ## Retry Behavior Overview Boto3's Standard retry mode includes the following mechanisms: * Maximum Retry Attempts: Default value set to 3, configurable via the `--aws-retries-max-attempts 5` argument. `0` disables retries. * Expanded Error Handling: Retries occur for a comprehensive set of errors. ``` # *Transient Errors/Exceptions* The retrier handles various temporary failures: RequestTimeout RequestTimeoutException PriorRequestNotComplete ConnectionError HTTPClientError # *Service-Side Throttling and Limit Errors* Retries occur for service-imposed rate limits and resource constraints: Throttling ThrottlingException ThrottledException RequestThrottledException TooManyRequestsException ProvisionedThroughputExceededException TransactionInProgressException RequestLimitExceeded BandwidthLimitExceeded LimitExceededException RequestThrottled SlowDown EC2ThrottledException ``` * Nondescriptive Transient Error Codes: The retrier applies retry logic to standard HTTP status codes signaling transient errors: 500, 502, 503, 504. * Exponential Backoff Strategy: Each retry attempt follows exponential backoff with a base factor of 2, ensuring progressive delay between retries. Maximum backoff time: 20 seconds ## Validating Retry Attempts For testing or modifying Prowler's behavior, use the following steps to confirm whether requests are being retried or abandoned: * Run prowler with `--log-level DEBUG` and `--log-file debuglogs.txt` * Search for retry attempts using `grep -i 'Retry needed' debuglogs.txt` This approach follows the [AWS documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html#checking-retry-attempts-in-your-client-logs), which states that if a retry is performed, a message starting with "Retry needed" will be prompted. It is possible to determine the total number of calls made using `grep -i 'Sending http request' debuglogs.txt | wc -l` # Installing Prowler in AWS CloudShell Source: https://docs.prowler.com/user-guide/providers/aws/cloudshell ## Following the Migration of AWS CloudShell from Amazon Linux 2 to Amazon Linux 2023 AWS CloudShell has migrated from Amazon Linux 2 to Amazon Linux 2023 [\[1\]](https://aws.amazon.com/about-aws/whats-new/2023/12/aws-cloudshell-migrated-al2023/) [\[2\]](https://docs.aws.amazon.com/cloudshell/latest/userguide/cloudshell-AL2023-migration.html). With this transition, Python 3.9 is now included by default in AL2023, eliminating the need for manual compilation. To install Prowler v4 in AWS CloudShell, follow the standard installation method using pip: ```shell theme={null} sudo bash adduser prowler su prowler pip install prowler cd /tmp prowler aws ``` ## Downloading Files from AWS CloudShell To download results from AWS CloudShell: * Select Actions → Download File. * Specify the full file path of each file you wish to download. For example, downloading a CSV file would require providing its complete path, as in: `/home/cloudshell-user/output/prowler-output-123456789012-20221220191331.csv` ## Cloning Prowler from GitHub Due to the limited storage in AWS CloudShell's home directory, installing uv dependencies for running Prowler from GitHub can be problematic. The following workaround ensures successful installation: ```shell theme={null} sudo bash adduser prowler su prowler git clone https://github.com/prowler-cloud/prowler.git cd prowler pip install uv mkdir /tmp/uv-cache UV_CACHE_DIR=/tmp/uv-cache uv sync source .venv/bin/activate python prowler-cli.py -v ``` # Getting Started With AWS on Prowler Source: https://docs.prowler.com/user-guide/providers/aws/getting-started-aws ## Prowler Cloud > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). [Prowler Cloud Onboarding AWS](https://www.youtube-nocookie.com/embed/RPgIWOCERzY) > Walkthrough video onboarding an AWS Account using Assumed Role. ### Step 1: Get Your AWS Account ID 1. Log in to the [AWS Console](https://console.aws.amazon.com) 2. Locate your AWS account ID in the top-right dropdown menu ![Account ID detail](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/aws-account-id.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=da915d98157afc0aa13de13abc7c6d79) ### Step 2: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Go to "Configuration" > "Providers" ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider" ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Amazon Web Services" ![Select AWS Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-aws.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=6144f93b9006a160890eb1223d1c05b4) 5. Enter your AWS Account ID and optionally provide a friendly alias ![Add account ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-account-id.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=1a46ec2888f5f577a0fbb7a3aa95f5fd) 6. Choose the preferred authentication method (next step) ![Select auth method](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/user-guide/providers/aws/img/select-auth-method.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=372efbfd0b3c0b0c808c2e5ce92ef2df) ### Step 3: Set Up AWS Authentication Before proceeding, choose the preferred authentication mode: **Credentials** * Quick scan using an IAM user's access keys * No extra setup in AWS * Static keys can be rotated or revoked at any time **Assumed Role** * Recommended for production * With AWS SDK Default as the credential source, no long-lived keys are stored in Prowler (Access & Secret Key still requires pasted keys) * Requires permission to create an IAM role in the target account *** #### Assume Role (Recommended) This method grants permanent access and is the recommended setup for production environments. ![Assume Role Overview](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/assume-role-overview.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=3d3809e06218a5b47ecbeb5c487e43df) For detailed instructions on how to create the role, see [Authentication > Assume Role](/user-guide/providers/aws/authentication#assume-role-recommended). 7. Once the role is created, go to the **IAM Console**, click the "ProwlerScan" role to open its details: ![ProwlerScan role info](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/prowler-scan-pre-info.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=4f28498bb4349d50e21a83c6f799751b) 8. Copy the **Role ARN** ![New Role Info](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/get-role-arn.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=11c33062b7a2ff512d3f35bdab554965) 9. Paste the ARN into the corresponding field in Prowler Cloud ![Input the Role ARN](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/paste-role-arn-prowler.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=a6ab8f248585d0e39d542eecd2965019) 10. Select the credential source Prowler should use to call `sts:AssumeRole`. The option label differs between deployments but both map to the same `aws-sdk-default` credential type: * **"Prowler Cloud will assume your IAM role"** (default in Prowler Cloud) / **"AWS SDK Default"** (in Prowler Local Server): Prowler uses the credentials available in the API and worker environment through the [AWS SDK default credential chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). In Prowler Local Server, these containers have no AWS credentials by default — see [Configuring AWS SDK Default for Prowler Local Server](/user-guide/providers/aws/authentication#configuring-aws-sdk-default-for-prowler-local-server) before choosing this option, or the connection test will fail with `InvalidClientTokenId`. * **Access & Secret Key**: Paste an IAM user's `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and optional `AWS_SESSION_TOKEN`) into the form. The IAM principal must be allowed to assume the target role and must match the `IAMPrincipal` parameter of the scan role template (default: `role/prowler*`). 11. Click "Next", then "Launch Scan" ![Next button in Prowler Cloud](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/next-button-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=624a621d2ffa88f221ef5398f0357b72) ![Launch Scan](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/launch-scan-button-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=c8d184bdf837c46cef06fca04d21c0e9) > [!NOTE] > > Check if your AWS Security Token Service (STS) has the EU (Ireland) endpoint active. If not, we will not be able to connect to your AWS account. > > If that is the case your STS configuration may look like this: > > ![AWS Role](https://mintcdn.com/prowler/9AoCN7Q_gXN7wF7l/images/sts-configuration.png?fit=max\&auto=format\&n=9AoCN7Q_gXN7wF7l\&q=85\&s=a8bbaf585580303c3d32c42431c9678d) > > To solve this issue, please activate the EU (Ireland) STS endpoint. *** #### Credentials (Static Access Keys) AWS accounts can also be configured using static credentials (not recommended for long-term use): ![Connect via credentials](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/connect-via-credentials.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=2d3bedcc7db00d6bcec9977fa87e654d) For detailed instructions on how to create the credentials, see [Authentication > Credentials](/user-guide/providers/aws/authentication#credentials). 1. Complete the form in Prowler Cloud and click "Next" ![Filled credentials page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/prowler-cloud-credentials-next.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=38e7ae1507efa4a99f0caec20f3821e4) 2. Click "Launch Scan" ![Launch Scan](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/launch-scan-button-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=c8d184bdf837c46cef06fca04d21c0e9) *** ## Prowler CLI ### Configure AWS Credentials To authenticate with AWS, use one of the following methods: ```console theme={null} aws configure ``` or ```console theme={null} export AWS_ACCESS_KEY_ID="ASXXXXXXX" export AWS_SECRET_ACCESS_KEY="XXXXXXXXX" export AWS_SESSION_TOKEN="XXXXXXXXX" ``` These credentials must be associated with a user or role with the necessary permissions to perform security checks. More details on Assume Role settings from the CLI in [Assume Role](/user-guide/providers/aws/role-assumption) page. ### AWS Profiles To use a custom AWS profile, specify it with the following command: ```console theme={null} prowler aws -p/--profile ``` ### Multi-Factor Authentication (MFA) For IAM entities requiring Multi-Factor Authentication (MFA), use the `--mfa` flag. Prowler prompts for the following values to initiate a new session: * **ARN of your MFA device** * **TOTP (time-based one-time password)** # Scanning Multiple AWS Accounts with Prowler Source: https://docs.prowler.com/user-guide/providers/aws/multiaccount Prowler enables security scanning across multiple AWS accounts by using the [Assume Role feature](/user-guide/providers/aws/role-assumption) and [integration with AWS Organizations feature](/user-guide/providers/aws/organizations). This approach allows execution from a single account with permissions to assume roles in the target accounts. ## Scanning Multiple Accounts Sequentially To scan specific accounts one at a time: * Define a variable containing the AWS account IDs to be scanned: ``` ACCOUNTS_LIST='11111111111 2222222222 333333333' ``` * Run Prowler with an IAM role that exists in all target accounts: (replace the `` with yours, that is to be consistent throughout all accounts): ``` ROLE_TO_ASSUME= for accountId in $ACCOUNTS_LIST; do prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME done ``` ## Scanning Multiple Accounts in Parallel * To scan multiple accounts simultaneously: Define the AWS accounts to be scanned with a variable: ``` ACCOUNTS_LIST='11111111111 2222222222 333333333' ``` * Run Prowler with an IAM role that exists in all target accounts: (replace the `` with yours, that is to be consistent throughout all accounts). The following example executes scanning across three accounts in parallel: ``` ROLE_TO_ASSUME= PARALLEL_ACCOUNTS="3" for accountId in $ACCOUNTS_LIST; do test "$(jobs | wc -l)" -ge $PARALLEL_ACCOUNTS && wait || true { prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME } & done ``` ## Scanning Multiple AWS Organization Accounts in Parallel Prowler enables parallel security scans across multiple AWS accounts within an AWS Organization. ### Retrieve Active AWS Accounts To efficiently scan multiple accounts within an AWS Organization, follow these steps: * Step 1: Retrieve a List of Active Accounts First, declare a variable containing all active accounts in your AWS Organization. Run the following command in your AWS Organizations Management account, ensuring that you have the necessary permissions: ``` ACCOUNTS_IN_ORG=$(aws organizations list-accounts --query Accounts[?Status==`ACTIVE`].Id --output text) ``` * Step 2: Run Prowler with Assumed Roles Use Prowler to assume roles across accounts in parallel. Modify `` to match the role that exists in all accounts and `` to your AWS Organizations Management account ID. ``` ROLE_TO_ASSUME= MGMT_ACCOUNT_ID= PARALLEL_ACCOUNTS="3" for accountId in $ACCOUNTS_IN_ORG; do test "$(jobs | wc -l)" -ge $PARALLEL_ACCOUNTS && wait || true { prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME \ --organizations-role arn:aws:iam::$MGMT_ACCOUNT_ID:role/$ROLE_TO_ASSUME } & done ``` # AWS Organizations in Prowler Source: https://docs.prowler.com/user-guide/providers/aws/organizations > [!NOTE] > > **Using Prowler Cloud?** You can onboard your entire AWS Organization through the UI with automatic account discovery, OU-aware tree selection, and bulk connection testing — no scripts or YAML files required. > > See [AWS Organizations](/user-guide/tutorials/prowler-cloud-aws-organizations) in Prowler Cloud for the full walkthrough. Prowler can integrate with AWS Organizations to manage the visibility and onboarding of accounts centrally. For the cross-provider organization lifecycle and capability comparison, see [Organizations Across Cloud Providers](/user-guide/organizations). When trusted access is enabled with the Organization, Prowler can discover accounts as they are created and even automate deployment of the Prowler Scan IAM Role. > ℹ️ Trusted access can be enabled in the Management Account from the AWS Console under **AWS Organizations → Settings → Trusted access for AWS CloudFormation StackSets**. When not using StackSets or Prowler and only needing to scan AWS Organization accounts using the CLI, it is possible to assume a role in each account manually or automate that logic with custom scripts. ## Retrieving AWS Account Details If AWS Organizations is enabled, Prowler can fetch detailed account information during scans, including: * Account Name * Email Address * ARN * Organization ID * Tags These details will be included alongside each security finding in the output. ### Enabling AWS Organizations Data Retrieval To retrieve AWS Organizations account details, use the `-O`/`--organizations-role ` argument. If this argument is not provided, Prowler will attempt to fetch the data automatically—provided the AWS account is a delegated administrator for the AWS Organization. > [!NOTE] > > For more information on AWS Organizations delegated administrator, refer to the official documentation [here](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html). The following command is an example: ```shell theme={null} prowler aws \ -O arn:aws:iam:::role/ ``` > [!NOTE] > > Ensure the IAM role used in your AWS Organizations management account has the following permissions:`organizations:DescribeAccount` and `organizations:ListTagsForResource`. Prowler will scan the AWS account and get the account details from AWS Organizations. ### Handling JSON Output In Prowler's JSON output, tags are encoded in Base64 to prevent formatting errors in CSV or JSON outputs. This ensures compatibility when exporting findings. ```json theme={null} "Account Email": "my-prod-account@domain.com", "Account Name": "my-prod-account", "Account ARN": "arn:aws:organizations::222222222222:account/o-abcde1234/111111111111", "Account Organization": "o-abcde1234", "Account tags": "\"eyJUYWdzIjpasf0=\"" ``` The additional fields in CSV header output are as follows: * ACCOUNT\_DETAILS\_EMAIL * ACCOUNT\_DETAILS\_NAME * ACCOUNT\_DETAILS\_ARN * ACCOUNT\_DETAILS\_ORG * ACCOUNT\_DETAILS\_TAGS ## Deploying Prowler IAM Roles Across AWS Organizations [Added in:  5.35.0](https://github.com/prowler-cloud/prowler/releases/tag/5.35.0) When onboarding multiple AWS accounts into Prowler Cloud, it is important to deploy the Prowler Scan IAM Role in each account. The most efficient way to do this across an AWS Organization is by leveraging AWS CloudFormation StackSets, which rolls out infrastructure—like IAM roles—to all accounts centrally from the Management or Delegated Admin account. ### Native CloudFormation StackSet Deployment (Recommended) The [Prowler Scan IAM Role CloudFormation template](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml) can deploy the role across your entire AWS Organization on its own—no third-party modules required. When launched in the **Management Account** (or a **Delegated Administrator** account) with `DeployStackSet=true` and `EnableOrganizations=true`, it creates a service-managed CloudFormation StackSet that rolls the ProwlerScan role out to every account under the target Organizational Unit (or the organization root), and keeps new accounts covered automatically through auto-deployment. To deploy from the CloudFormation console: open **CloudFormation → Create stack → With new resources**, choose **Upload a template file** and select `prowler-scan-role.yml` (or paste its S3 URL), then set the parameters below on the **Specify stack details** step. Leave the **Configure stack options** step at its defaults. Deploy a single CloudFormation Stack in the Management Account with the following parameters: | Parameter | Description | Default | | - | - | - | | `ExternalId` | External ID provided by Prowler Cloud to secure role assumption. | — | | `DeployLocalRole` | Create the ProwlerScan role in this (Management) account. | `true` | | `DeployStackSet` | Create a service-managed StackSet that deploys the role to member accounts. | `false` | | `AWSOrganizationalUnitId` | Target OU (`ou-xxxx-yyyyyyyy`) or organization root (`r-xxxx`) for the StackSet. Required when `DeployStackSet=true`. | `""` | | `DeployFromDelegatedAdmin` | Set to `true` when deploying from a Delegated Administrator account instead of the Management Account (uses `CallAs: DELEGATED_ADMIN`). | `false` | | `EnableOrganizations` | Add AWS Organizations permissions to the Management Account role: read-only account discovery plus the StackSet-management permissions the deployment needs. Set to `true` when deploying in the Management Account. | `false` | | `FailureTolerancePercentage` | Percentage of accounts in which the StackSet operation can fail before CloudFormation stops the operation. | `10` | | `RetainStacksOnAccountRemoval` | Keep the role in an account after it leaves the Organization or OU. | `false` | > [!WARNING] > > On the review step, select **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"** — the template provisions the named `ProwlerScan` IAM role, so the stack requires the `CAPABILITY_NAMED_IAM` capability and fails without this acknowledgment. (The quick-create link handles this for you.) > [!NOTE] > > The service-managed StackSet does **not** deploy to the Management Account itself. Keeping `DeployLocalRole=true` ensures the role also exists there, so a single stack covers both the Management and member accounts. > > Trusted access for CloudFormation StackSets must be enabled in the Organization (see the note at the top of this page) before `DeployStackSet` will work. > > Deploying for the CLI or a self-hosted Prowler (not Prowler Cloud)? Also set `AccountId` to the account you assume the role from and `IAMPrincipal` to your identity — the defaults target Prowler Cloud. See [Aligning the trust policy with your identity](/user-guide/providers/aws/authentication#trust-policy-align-iamprincipal-with-your-identity). ### Alternative: Deploy with Terraform * **Use StackSets** from the **Management Account** (or a Delegated Admin/Security Account). * **Use Terraform** to orchestrate the deployment. * **Use the official CloudFormation template** provided by Prowler. * Target specific Organizational Units (OUs) or the entire Organization. > [!NOTE] > > A detailed community article this implementation is based on is available here: > [Deploy IAM Roles Across an AWS Organization as Code (Unicrons)](https://unicrons.cloud/en/2024/10/14/deploy-iam-roles-across-an-aws-organization-as-code/) > This guide has been adapted with permission and aligned with Prowler’s IAM role requirements. *** ### Step-by-Step Guide Using Terraform Below is a ready Terraform snippet that deploys the [Prowler Scan IAM Role CloudFormation template](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml) across the AWS Organization using StackSets: ```hcl title="main.tf" theme={null} data "aws_caller_identity" "this" {} data "aws_organizations_organization" "this" {} module "prowler-scan-role" { source = "unicrons/organization-iam-role/aws" stack_set_name = "prowler-scan-role" stack_set_description = "Deploy Prowler Scan IAM Role across all organization accounts" template_path = "${path.root}/prowler-scan-role.yaml" template_parameters = { ExternalId = "<< external ID >>" # Replace with the External ID provided by Prowler Cloud } # Specific OU IDs can be specified instead of root organizational_unit_ids = [data.aws_organizations_organization.this.roots[0].id] } ``` #### `prowler-scan-role.yaml` Download or reference the official CloudFormation template directly from GitHub: * [prowler-scan-role.yml](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml) *** ### IAM Role: External ID Support Include the `ExternalId` parameter in the StackSet if required by the organization's Prowler Cloud setup. This ensures secure cross-account access for scanning. *** When encountering issues during deployment or needing to target specific OUs or environments (e.g., dev/staging/prod), reach out to the Prowler team via [Slack Community](https://prowler.com/slack) or [Support](mailto:support@prowler.com). ## Extra: Run Prowler Across All Accounts in AWS Organizations by Assuming Roles ### Running Prowler Across All AWS Organization Accounts 1. To run Prowler across all accounts in AWS Organizations, first retrieve a list of accounts that are not suspended: ```shell theme={null} ACCOUNTS_IN_ORGS=$(aws organizations list-accounts \ --query "Accounts[?Status=='ACTIVE'].Id" \ --output text \ ) ``` 2. Then run Prowler to assume a role (same in all members) per each account: ```shell theme={null} for accountId in $ACCOUNTS_IN_ORGS; do prowler aws \ -O arn:aws:iam:::role/ \ -R arn:aws:iam::"${accountId}":role/; done ``` > [!NOTE] > > This same loop structure can be adapted to scan a predefined list of accounts using a variable like the following: `ACCOUNTS_LIST='11111111111 2222222222 333333333'` # AWS Regions and Partitions Source: https://docs.prowler.com/user-guide/providers/aws/regions-and-partitions By default Prowler is able to scan the following AWS partitions: * Commercial: `aws` * China: `aws-cn` * European Sovereign Cloud: `aws-eusc` * GovCloud (US): `aws-us-gov` > [!NOTE] > > To check the available regions for each partition and service, refer to: [aws\_regions\_by\_service.json](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_regions_by_service.json) ## Scanning AWS China, European Sovereign Cloud and GovCloud Partitions in Prowler When scanning the China (`aws-cn`), European Sovereign Cloud (`aws-eusc`) or GovCloud (`aws-us-gov`) partitions, ensure one of the following: * Your AWS credentials include a valid region within the desired partition. * Specify the regions to audit within that partition using the `-f/--region` flag. * Declare the partition with the `PROWLER_AWS_PARTITION` environment variable, set to `aws`, `aws-cn`, `aws-eusc` or `aws-us-gov`. > [!NOTE] > > Refer to: [https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials) for more information about the AWS credential configuration. ### Declaring the Partition `PROWLER_AWS_PARTITION` tells Prowler which partition the scan runs against, without relying on a region being configured: ```bash theme={null} export PROWLER_AWS_PARTITION="aws-us-gov" ``` It matters most where nothing else says. Resolving an identity means calling STS before anything is known about the credentials, and with no region configured Prowler would otherwise start from the commercial endpoints. Declaring the partition makes that first call go to the right place, which is the difference between a scan that starts and one that fails on an endpoint the credentials cannot use. A region configured for the session still wins when it belongs to the declared partition, so a deployment in `us-gov-west-1` is not sent to `us-gov-east-1`. A region belonging to a different partition is ignored, since a partition that has been declared explicitly is the more deliberate statement of the two. When no configured region says which one to prefer, the first region of the partition is tried, and up to two more follow if it cannot be reached. A network that routes to only one region of its partition therefore works without having to declare which one that is. Only a connection failure moves on to the next region: a credential error is reported from the first, since it would be the same everywhere. A region excluded from the scan is tried last, so it is avoided whenever another region of the partition answers. > [!NOTE] > > Set it wherever the scan runs. For deployments that scan from containers, that means the environment of the containers doing the scanning, not only the one accepting the request. ### Scanning Specific Regions To scan a particular AWS region with Prowler, use: ```console theme={null} prowler aws -f/--region eu-west-1 us-east-1 ``` ### Excluding Specific Regions To scan all supported AWS regions except a specific subset, use the `--excluded-region` flag: ```console theme={null} prowler aws --excluded-region eu-west-1 me-south-1 ``` You can also configure the exclusion list with the `PROWLER_AWS_DISALLOWED_REGIONS` environment variable as a comma-separated list: ```console theme={null} export PROWLER_AWS_DISALLOWED_REGIONS="eu-west-1,me-south-1" prowler aws ``` Or with the AWS provider configuration in `config.yaml`: ```yaml theme={null} aws: disallowed_regions: - eu-west-1 - me-south-1 ``` When more than one source is set, precedence is: 1. `--excluded-region` 2. `PROWLER_AWS_DISALLOWED_REGIONS` 3. `aws.disallowed_regions` in `config.yaml` > [!NOTE] > > For Prowler Local Server or API-triggered scans, set `PROWLER_AWS_DISALLOWED_REGIONS` in the runtime environment of the backend scan containers such as `api` and `worker`. The `ui` container does not enforce AWS region selection. ### AWS Credentials Configuration For details on configuring AWS credentials, refer to the following [Botocore](https://github.com/boto/botocore) [file](https://github.com/boto/botocore/blob/22a19ea7c4c2c4dd7df4ab8c32733cba0c7597a4/botocore/data/partitions.json). ## Scanning AWS Partitions in Prowler ### AWS China To scan an account in the AWS China partition (`aws-cn`): * By using the `-f/--region` flag: ``` prowler aws --region cn-north-1 cn-northwest-1 ``` * By using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`: ``` [default] aws_access_key_id = XXXXXXXXXXXXXXXXXXX aws_secret_access_key = XXXXXXXXXXXXXXXXXXX region = cn-north-1 ``` > [!NOTE] > > With this configuration, all partition regions will be scanned without needing the `-f/--region` flag ### AWS GovCloud (US) To scan an account in the AWS GovCloud (US) partition (`aws-us-gov`): * By using the `-f/--region` flag: ``` prowler aws --region us-gov-east-1 us-gov-west-1 ``` * By using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`: ``` [default] aws_access_key_id = XXXXXXXXXXXXXXXXXXX aws_secret_access_key = XXXXXXXXXXXXXXXXXXX region = us-gov-east-1 ``` > [!NOTE] > > With this configuration, all partition regions will be scanned without needing the `-f/--region` flag ### AWS European Sovereign Cloud To scan an account in the AWS European Sovereign Cloud partition (`aws-eusc`): * By using the `-f/--region` flag: ``` prowler aws --region eusc-de-east-1 ``` * By using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`: ``` [default] aws_access_key_id = XXXXXXXXXXXXXXXXXXX aws_secret_access_key = XXXXXXXXXXXXXXXXXXX region = eusc-de-east-1 ``` > [!NOTE] > > With this configuration, all partition regions will be scanned without needing the `-f/--region` flag ### AWS ISO (US & Europe) The AWS ISO partitions—commonly referred to as "secret partitions"—are air-gapped from the Internet, and Prowler does not have a built-in way to scan them. To audit an AWS ISO partition, manually update [aws\_regions\_by\_service.json](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_regions_by_service.json) to include the partition, region, and services. For example: ```json theme={null} "iam": { "regions": { "aws": [ "eu-west-1", "us-east-1", ], "aws-cn": [ "cn-north-1", "cn-northwest-1" ], "aws-eusc": [ "eusc-de-east-1" ], "aws-us-gov": [ "us-gov-east-1", "us-gov-west-1" ], "aws-iso": [ "aws-iso-global", "us-iso-east-1", "us-iso-west-1" ], "aws-iso-b": [ "aws-iso-b-global", "us-isob-east-1" ], "aws-iso-e": [], } }, ``` # Resource ARN-based Scanning Source: https://docs.prowler.com/user-guide/providers/aws/resource-arn-based-scan Prowler enables scanning of resources based on specific AWS Resource ARNs. ## Resource ARN-Based Scanning Prowler enables scanning of resources based on specific AWS Resource [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). To perform this scan, use the designated flag `--resource-arn` followed by one or more ARNs, separated by spaces. ``` prowler aws --resource-arn arn:aws:iam::012345678910:user/test arn:aws:ec2:us-east-1:123456789012:vpc/vpc-12345678 ``` Example: This configuration scans only the specified two resources using their ARNs. # AWS Assume Role in Prowler (CLI) Source: https://docs.prowler.com/user-guide/providers/aws/role-assumption ## Authentication Overview Prowler leverages the AWS SDK (Boto3) for authentication, following standard AWS authentication methods. ### Running Prowler Against Multiple Accounts To execute Prowler across multiple AWS accounts using IAM Assume Role, choose one of the following approaches: 1. Custom Profile Configuration Set up a custom profile inside `~/.aws/config` with the necessary role information. Then call the profile using `prowler aws -p/--profile your-custom-profile`. * Role-Chaining Example Profile The `credential_source` parameter can be set to `Environment`, `Ec2InstanceMetadata`, or `EcsContainer`. * Using an Alternative Named Profile Instead of the `credential_source` parameter, `source_profile` can be used to specify a separate named profile. This profile must contain IAM user credentials with permissions to assume the target role. For additional details, refer to the AWS Assume Role documentation: [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html). ``` [profile crossaccountrole] role_arn = arn:aws:iam::234567890123:role/SomeRole credential_source = EcsContainer ``` 2. Using IAM Role Assumption in Prowler To allow Prowler to retrieve temporary credentials by using `Boto3` and run assessments on the specified account, use the `-R`/`--role ` flag. ```sh theme={null} prowler aws -R arn:aws:iam:::role/ ``` **Defining Session Duration and External ID** Optionally, specify the session duration (in seconds, default: 3600) and the external ID for role assumption: ```sh theme={null} prowler aws -T/--session-duration -I/--external-id -R arn:aws:iam:::role/ ``` ## Custom Role Session Name in Prowler ### Setting a Custom Session Name Prowler allows you to specify a custom Role Session name using the following flag: ```console theme={null} prowler aws --role-session-name ``` > [!NOTE] > > If not specified, it defaults to `ProwlerAssessmentSession`. ## Role MFA Authentication If your IAM Role is configured with Multi-Factor Authentication (MFA), use `--mfa` along with `-R`/`--role `. Prowler will prompt you to input the following values to obtain a temporary session for the IAM Role provided: * ARN of your MFA device * TOTP (Time-Based One-Time Password) ## Creating a Role for One or Multiple Accounts To create an IAM role that can be assumed in one or multiple AWS accounts, use either a CloudFormation Stack or StackSet with the provided [template](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml). The template requires the following parameters: * **ExternalId:** A unique identifier to prevent the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) * **AccountId:** *(Optional)* AWS Account ID that will assume the role (default: Prowler Cloud account) * **IAMPrincipal:** *(Optional)* The IAM principal allowed to assume the role (default: `role/prowler*`) > [!WARNING] > > From the CLI you assume the role with **your own** identity, not from Prowler Cloud. The `AccountId` and `IAMPrincipal` defaults target Prowler Cloud, so set **`AccountId`** to the account you run Prowler from and **`IAMPrincipal`** to your identity (for example `role/` or `user/`). Otherwise `sts:AssumeRole` fails with `AccessDenied`. See [Aligning the trust policy with your identity](/user-guide/providers/aws/authentication#trust-policy-align-iamprincipal-with-your-identity). > [!NOTE] > > To deploy the role across an entire AWS Organization from a single stack (Management Account role plus a service-managed StackSet for the member accounts), the template also accepts `DeployLocalRole`, `DeployStackSet`, `AWSOrganizationalUnitId`, `DeployFromDelegatedAdmin`, `EnableOrganizations`, `FailureTolerancePercentage`, and `RetainStacksOnAccountRemoval`. See [AWS Organizations in Prowler](/user-guide/providers/aws/organizations#native-cloudformation-stackset-deployment-recommended) for the full parameter reference. When running Prowler CLI, include the External ID using the `-I/--external-id` flag: ```sh theme={null} prowler aws -R arn:aws:iam:::role/ProwlerScan -I ``` > [!NOTE] > > **Session Duration Considerations**: Depending on the number of checks performed and the size of your infrastructure, Prowler may require more than 1 hour to complete. Use the `-T ` option to allow up to 12 hours (43,200 seconds). If you need more than 1 hour, modify the *“Maximum CLI/API session duration”* setting for the role. Learn more [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session). > > ⚠️ Important: If assuming roles via role chaining, there is a hard limit of 1 hour. Whenever possible, avoid role chaining to prevent session expiration issues. More details are available in footnote 1 below the table in the [AWS IAM guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). # Sending Reports to an AWS S3 Bucket Source: https://docs.prowler.com/user-guide/providers/aws/s3 To save reports directly in an S3 bucket, use: `-B`/`--output-bucket`. ```sh theme={null} prowler aws -B my-bucket ``` ### Custom Folder and Filename For a custom folder and/or filename, specify: `-o`/`--output-directory` and/or `-F`/`--output-filename`. ```sh theme={null} prowler aws \ -B my-bucket \ --output-directory test-folder \ --output-filename output-filename ``` ### Custom Output Formats By default, Prowler sends HTML, JSON, and CSV output formats. To specify a single output format, use the `-M`/`--output-modes` flag. ```sh theme={null} prowler aws -M csv -B my-bucket ``` > [!NOTE] > > If you prefer using the initial credentials instead of the assumed role credentials for uploading reports, use `-D`/`--output-bucket-no-assume` instead of `-B`/`--output-bucket`. > [!WARNING] > > Ensure the credentials used have write permissions for the `s3:PutObject` where reports will be uploaded. # AWS Security Hub Integration with Prowler Source: https://docs.prowler.com/user-guide/providers/aws/securityhub Prowler natively supports **official integration** with [AWS Security Hub](https://aws.amazon.com/security-hub), allowing security findings to be sent directly. This integration enables **Prowler** to import its findings into AWS Security Hub. To activate the integration, follow these steps in at least one AWS region within your AWS account: ## Enabling AWS Security Hub for Prowler Integration To enable the integration, follow these steps in **at least** one AWS region within your AWS account. Since **AWS Security Hub** is a region-based service, it must be activated in each region where security findings need to be collected. **Configuration Options** AWS Security Hub can be enabled using either of the following methods: > [!NOTE] > > Enabling this integration incurs costs in AWS Security Hub. Refer to [this information](https://aws.amazon.com/security-hub/pricing/) for details. ### Using the AWS Management Console #### Enabling AWS Security Hub for Prowler Integration If AWS Security Hub is already enabled, you can proceed to the [next section](#enabling-prowler-integration-in-aws-security-hub). 1. Enable AWS Security Hub via Console: Open the **AWS Security Hub** console: [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 2. Ensure you are in the correct AWS region, then select “**Go to Security Hub**”. ![](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/enable.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=4721d8b5198cfcfd2b25d6e7cf436170) 3. In the “Security Standards” section, review the supported security standards. Select the checkbox for each standard you want to enable, or clear it to disable a standard. 4. Choose “**Enable Security Hub**”. ![](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/enable-2.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=5a874ddd14fb5e161c453a2c02f565af) #### Enabling Prowler Integration in AWS Security Hub If the Prowler integration is already enabled in AWS Security Hub, you can proceed to the [next section](#sending-findings-to-aws-security-hub) and begin sending findings. Once **AWS Security Hub** is activated, **Prowler** must be enabled as partner integration to allow security findings to be sent to it. 1. Enabling AWS Security Hub via Console Open the **AWS Security Hub** console: [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 2. Select the “**Integrations**” tab from the right-side menu bar. ![](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/enable-partner-integration.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=5514a8e23d3a4cb0ddae31f0ab2f2b7a) 3. Search for “*Prowler*” in the text search box and the **Prowler** integration will appear. 4. Click “**Accept Findings**” to authorize **AWS Security Hub** to receive findings from **Prowler**. ![](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/enable-partner-integration-2.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=42f6c2dd297aad642cbdde88fe93a80b) 5. A new modal will appear to confirm that the integration with **Prowler** is being enabled. ![](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/enable-partner-integration-3.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=96777292a31bc20bcf91cddefc2634ad) 6. Click “**Accept Findings**”, to authorize **AWS Security Hub** to receive findings from Prowler. ![](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/enable-partner-integration-4.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=1c3f7f66c211d95d50b148c2b4683c06) ### Using AWS CLI To enable **AWS Security Hub** and integrate **Prowler**, execute the following AWS CLI commands: **Step 1: Enable AWS Security Hub** Run the following command to activate AWS Security Hub in the desired region: ```shell theme={null} aws securityhub enable-security-hub --region ``` > [!NOTE] > > This command requires the `securityhub:EnableSecurityHub` permission. Ensure you set the correct AWS region where you want to enable AWS Security Hub. **Step 2: Enable Prowler Integration** Once **AWS Security Hub** is activated, **Prowler** must be enabled as partner integration to allow security findings to be sent to it. Run the following AWS CLI commands: ```shell theme={null} aws securityhub enable-import-findings-for-product --region eu-west-1 --product-arn arn:aws:securityhub:::product/prowler/prowler ``` > [!NOTE] > > Specify the AWS region where you want to enable the integration. Ensure the region is correctly set within the ARN value. This command requires the `securityhub:EnableImportFindingsForProduct` permission. ## Sending Findings to AWS Security Hub Once AWS Security Hub is enabled, findings can be sent using the following commands: For all regions: ```sh theme={null} prowler aws --security-hub ``` For a specific region (e.g., eu-west-1): ```sh theme={null} prowler --security-hub --region eu-west-1 ``` > [!NOTE] > > It is recommended to send only fails to Security Hub and that is possible adding `--status FAIL` to the command. You can use, instead of the `--status FAIL` argument, the `--send-sh-only-fails` argument to save all the findings in the Prowler outputs but just to send FAIL findings to AWS Security Hub. > > Since Prowler performs checks to all regions by default you may need to filter by region when running Security Hub integration, as shown in the example above. Remember to enable Security Hub in the region or regions you need by calling `aws securityhub enable-security-hub --region ` and run Prowler with the option `-f/--region ` (if no region is used it will try to push findings in all regions hubs). Prowler will send findings to the Security Hub on the region where the scanned resource is located. > > To have updated findings in Security Hub you have to run Prowler periodically. Once a day or every certain amount of hours. ### Viewing Prowler Findings in AWS Security Hub After enabling **AWS Security Hub**, findings from **Prowler** will be available in the configured AWS regions. Reviewing Prowler Findings in **AWS Security Hub**: 1. Enabling AWS Security Hub via Console Open the **AWS Security Hub** console: [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 2. Select the “**Findings**” tab from the right-side menu bar. ![](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/findings.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=bd653661cdec1a703136af76a9db4412) 3. Use the search box filters and apply the “**Product Name**” filter with the value *Prowler* to display findings sent by **Prowler**. 4. Click the check “**Title**” to access its detailed view, including its history and status. ![](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/finding-details.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=b6483d0a5d4a7bf9517a19a7f713c308) #### Compliance Information As outlined in the Requirements section, the detailed view includes compliance details for each finding reported by **Prowler**. ## Sending Findings to Security Hub with IAM Role Assumption ### Multi-Account AWS Auditing When auditing a multi-account AWS environment, Prowler allows you to send findings to a Security Hub in another account by assuming an IAM role from that target account. #### Using an IAM Role to Send Findings To send findings to Security Hub, use the `-R` flag in the Prowler command: ```sh theme={null} prowler --security-hub --role arn:aws:iam::123456789012:role/ProwlerExecutionRole ``` > [!NOTE] > > The specified IAM role must have the necessary permissions to send findings to Security Hub. For details on the required permissions, refer to the IAM policy: [prowler-additions-policy.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-additions-policy.json) ## Sending Only Failed Findings to AWS Security Hub When using **AWS Security Hub** integration, **Prowler** allows sending only failed findings (`FAIL`), helping reduce **AWS Security Hub** usage costs. To enable this, add the `--status FAIL` flag to the Prowler command: ```sh theme={null} prowler --security-hub --status FAIL ``` **Configuring Findings Output** Instead of using `--status FAIL`, the `--send-sh-only-fails` argument to store all findings in Prowler outputs while sending only FAIL findings to AWS Security: ```sh theme={null} prowler --security-hub --send-sh-only-fails ``` ## Skipping Updates for Findings in Security Hub By default, Prowler archives any findings in Security Hub that were not detected in the latest scan. To prevent older findings from being archived, use the `--skip-sh-update` option: ```sh theme={null} prowler --security-hub --skip-sh-update ``` # Tag-based scan Source: https://docs.prowler.com/user-guide/providers/aws/tag-based-scan Prowler provides the capability to scan only resources containing specific tags. To execute this, use the designated flag `--resource-tags` followed by the tags `Key=Value`, separated by spaces. ``` prowler aws --resource-tags Environment=dev Project=prowler ``` This configuration scans only resources that contain both specified tags. # Threat Detection in AWS with Prowler Source: https://docs.prowler.com/user-guide/providers/aws/threat-detection Prowler enables threat detection in AWS by analyzing CloudTrail log records. To execute threat detection checks, use the following command: ``` prowler aws --category threat-detection ``` This command runs checks to detect: * `cloudtrail_threat_detection_privilege_escalation`: Privilege escalation attacks * `cloudtrail_threat_detection_enumeration`: Enumeration attacks * `cloudtrail_threat_detection_llm_jacking`: LLM Jacking attacks > [!NOTE] > > Threat detection checks are executed only when the `--category threat-detection` flag is used, due to performance considerations. ## Config File for Threat Detection To manage the behavior of threat detection checks, edit the configuration file located in `config.yaml` file from `/prowler/config`. The following attributes can be modified, all related to threat detection: * `threat_detection_privilege_escalation_threshold`: Defines the percentage of actions required to classify an event as a privilege escalation attack. Default: 0.2 (20%) * `threat_detection_privilege_escalation_minutes`: Specifies the time window (in minutes) to search for privilege escalation attack patterns. Default: 1440 minutes (24 hours). * `threat_detection_privilege_escalation_actions`: Lists the default actions associated with privilege escalation attacks. * `threat_detection_enumeration_threshold`: Defines the percentage of actions required to classify an event as an enumeration attack. Default: 0.3 (30%) * `threat_detection_enumeration_minutes`: Specifies the time window (in minutes) to search for enumeration attack patterns. Default: 1440 minutes (24 hours). * `threat_detection_enumeration_actions`: Lists the default actions associated with enumeration attacks. * `threat_detection_llm_jacking_threshold`: Defines the percentage of actions required to classify an event as LLM jacking attack. Default: 0.4 (40%) * `threat_detection_llm_jacking_minutes`: Specifies the time window (in minutes) to search for LLM jacking attack patterns. Default: 1440 minutes (24 hours). * `threat_detection_llm_jacking_actions`: Lists the default actions associated with LLM jacking attacks. Modify these attributes in the configuration file to fine-tune threat detection checks based on your security requirements. # Azure Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/azure/authentication Prowler for Azure supports multiple authentication types. Authentication methods vary between Prowler Cloud and Prowler CLI: **Prowler Cloud:** * [**Service Principal Application**](#service-principal-application-authentication-recommended) **Prowler CLI:** * [**Service Principal Application**](#service-principal-application-authentication-recommended) (**Recommended**) * [**AZ CLI credentials**](#az-cli-authentication) * [**Interactive browser authentication**](#browser-authentication) * [**Managed Identity Authentication**](#managed-identity-authentication) ## Required Permissions Prowler for Azure requires two types of permission scopes: ### Microsoft Entra ID Permissions These permissions allow Prowler to retrieve metadata from the assumed identity and perform specific Entra checks. While not mandatory for execution, they enhance functionality. #### Assigning Required API Permissions Assign the following Microsoft Graph permissions: * `AuditLog.Read.All` * `Directory.Read.All` * `Policy.Read.All` > [!NOTE] > > Replace `Directory.Read.All` with `Domain.Read.All` for more restrictive permissions. Note that Entra checks related to DirectoryRoles and GetUsers will not run with this permission. > [tab] Azure Portal > > 1. Go to your App Registration > "API permissions" > > ![API Permission Page](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/api-permissions-page.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=ac84b5ba3499bfb2fa26297865316c9d) > > 2. Click "+ Add a permission" > "Microsoft Graph" > "Application permissions" > > ![Add API Permission](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/add-api-permission.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=a103400e3e69094888436a0c3977dc15) > > ![Microsoft Graph Detail](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/microsoft-graph-detail.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=e11fa3cc1b87fe5425bbf78ecfe4d8e4) > > 3. Search and select: > > * `AuditLog.Read.All` > * `Directory.Read.All` > * `Policy.Read.All` > > ![Permission Screenshots](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/domain-permission.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=3f242eeaca4c3cb8e4f18d502a1f1010) > > 4. Click "Add permissions", then grant admin consent > > ![Grant Admin Consent](https://mintcdn.com/prowler/CpaQOQ_SLaLD3icu/images/providers/grant-admin-consent.png?fit=max\&auto=format\&n=CpaQOQ_SLaLD3icu\&q=85\&s=f4256d0f23bc0b45cfdd6310dec04f9a) > > ![Granted Admin Consent](https://mintcdn.com/prowler/CpaQOQ_SLaLD3icu/images/providers/granted-admin-consent.png?fit=max\&auto=format\&n=CpaQOQ_SLaLD3icu\&q=85\&s=257ee5873396531c67d1d82f57a084d5) > [tab] Azure CLI > > 1. To grant permissions to a Service Principal, execute the following command in a terminal: > > ```console theme={null} > az ad app permission add --id {appId} --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role 246dd0d5-5bd0-4def-940b-0421030a5b68=Role b0afded3-3588-46d8-8b3d-9842eff778da=Role > ``` ### Subscription Scope Permissions These permissions are required to perform security checks against Azure resources. The following **RBAC roles** must be assigned per subscription to the entity used by Prowler: * `Reader` – Grants read-only access to Azure resources. * `ProwlerRole` – A custom role with minimal permissions needed for some specific checks, defined in the [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json). #### Assigning "Reader" Role at the Subscription Level By default, Prowler scans all accessible subscriptions. If you need to audit specific subscriptions, you must assign the necessary role `Reader` for each one. For streamlined and less repetitive role assignments in multi-subscription environments, refer to the [following section](/user-guide/providers/azure/subscriptions#recommendation-for-managing-multiple-subscriptions). > [tab] Azure Portal > > 1. To grant Prowler access to scan a specific Azure subscription, follow these steps in Azure Portal: > Navigate to the subscription you want to audit with Prowler. > > 2. In the left menu, select "Access control (IAM)". > > 3. Click "+ Add" and select "Add role assignment". > > 4. In the search bar, enter `Reader`, select it and click "Next". > > 5. In the "Members" tab, click "+ Select members", then add the accounts to assign this role. > > 6. Click "Review + assign" to finalize and apply the role assignment. > > ![Adding the Reader Role to a Subscription](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/add-reader-role.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=1186944b7cb1768d439575333a86ba7e) > [tab] Azure CLI > > 1. Open a terminal and execute the following command to assign the `Reader` role to the identity that is going to be assumed by Prowler: > > ```console theme={null} > az role assignment create --role "Reader" --assignee --scope /subscriptions/ > ``` #### Assigning "ProwlerRole" Permissions at the Subscription Level Some read-only permissions required for specific security checks are not included in the built-in Reader role. To support these checks, Prowler utilizes a custom role, defined in [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json). Once created, this role can be assigned following the same process as the `Reader` role. The checks requiring this `ProwlerRole` can be found in this [section](/user-guide/providers/azure/authentication#checks-requiring-prowlerrole). > [tab] Azure Portal > > 1. Download the [Prowler Azure Custom Role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json) > > ![Azure Custom Role](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/download-prowler-role.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=ff7b92abcad67a42d1ec345100d94c57) > > 2. Modify `assignableScopes` to match your Subscription ID (e.g. `/subscriptions/xxxx-xxxx-xxxx-xxxx`) > > 3. Go to your Azure Subscription > "Access control (IAM)" > > ![IAM Page](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/iam-azure-page.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=b0a212012fda73b4c4f5bc4d09eb584b) > > 4. Click "+ Add" > "Add custom role", choose "Start from JSON" and upload the modified file > > ![Add custom role via JSON](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/add-custom-role-json.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=f1d7267ffa6d32df7f8275f143bea552) > > 5. Click "Review + Create" to finish > > ![Select review and create](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/review-and-create.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=c45be9762d087933c0ce5d806b51bbfa) > > 6. Return to "Access control (IAM)" > "+ Add" > "Add role assignment" > > * Assign the `Reader` role to the Application created in the previous step > * Then repeat the same process assigning the custom `ProwlerRole` > > ![Role Assignment](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/add-role-assigment.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=3c587786bde99247490fd33b96323105) > > > [!NOTE] > > > > The `assignableScopes` field in the JSON custom role file must be updated to reflect the correct subscription or management group. Use one of the following formats: `/subscriptions/` or `/providers/Microsoft.Management/managementGroups/`. > [tab] Azure CLI > > 1. To create a new custom role, open a terminal and execute the following command: > > ```console theme={null} > az role definition create --role-definition '{ > "Name": "ProwlerRole", > "IsCustom": true, > "Description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.", > "AssignableScopes": [ > "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // USE YOUR SUBSCRIPTION ID > ], > "Actions": [ > "Microsoft.Web/sites/host/listkeys/action", > "Microsoft.Web/sites/config/list/Action" > ] > }' > ``` > > 2. If the command is executed successfully, the output is going to be similar to the following: > > ```json theme={null} > { > "assignableScopes": [ > "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" > ], > "createdBy": null, > "createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00", > "description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.", > "id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", > "name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", > "permissions": [ > { > "actions": [ > "Microsoft.Web/sites/host/listkeys/action", > "Microsoft.Web/sites/config/list/Action" > ], > "condition": null, > "conditionVersion": null, > "dataActions": [], > "notActions": [], > "notDataActions": [] > } > ], > "roleName": "ProwlerRole", > "roleType": "CustomRole", > "type": "Microsoft.Authorization/roleDefinitions", > "updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", > "updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00" > } > ``` ### Additional Resources For more detailed guidance on subscription management and permissions: * [Azure subscription permissions](/user-guide/providers/azure/subscriptions) * [Create Prowler Service Principal](/user-guide/providers/azure/create-prowler-service-principal) > [!WARNING] > > Some permissions in `ProwlerRole` involve **write access**. If a `ReadOnly` lock is attached to certain resources, you may encounter errors, and findings for those checks will not be available. #### Checks Requiring `ProwlerRole` The following security checks require the `ProwlerRole` permissions for execution. Ensure the role is assigned to the identity assumed by Prowler before running these checks: * `app_function_access_keys_configured` * `app_function_application_insights_enabled` * `app_function_ftps_deployment_disabled` * `app_function_latest_runtime_version` *** ## Service Principal Application Authentication (Recommended) This method is required for Prowler Cloud and recommended for Prowler CLI. ### Creating the Service Principal For more information, see [Creating Prowler Service Principal](/user-guide/providers/azure/create-prowler-service-principal). ### Environment Variables (CLI) For Prowler CLI, set up the following environment variables: ```console theme={null} export AZURE_CLIENT_ID="XXXXXXXXX" export AZURE_TENANT_ID="XXXXXXXXX" export AZURE_CLIENT_SECRET="XXXXXXX" ``` Execution with the `--sp-env-auth` flag fails if these variables are not set or exported. ## AZ CLI Authentication *Available only for Prowler CLI* Use stored Azure CLI credentials: ```console theme={null} prowler azure --az-cli-auth ``` ## Managed Identity Authentication *Available only for Prowler CLI* Authenticate via Azure Managed Identity when running Prowler on Azure resources (VMs, Container Instances, Azure Functions, etc.): ```console theme={null} prowler azure --managed-identity-auth ``` ### Prerequisites Before using Managed Identity authentication, the following steps are required: 1. **Enable Managed Identity** on the Azure resource (e.g., VM, Container Instance) 2. **Assign the required permissions** to the Managed Identity on the target subscription(s) to scan > [!WARNING] > > A common misconception is that enabling a Managed Identity on a resource automatically grants it permissions. **This is not the case.** Without explicit role assignments, Prowler will be unable to scan subscriptions and will return authorization errors, resulting in incomplete security assessments. The Managed Identity itself is a service principal that must be explicitly granted Reader and ProwlerRole permissions on each subscription to scan. ### Step-by-Step Setup Guide #### Step 1: Enable Managed Identity on the Azure Resource > [tab] Azure VM > > **Via Azure Portal:** > > 1. Navigate to the VM in Azure Portal > 2. Select "Identity" from the left menu under "Security" > 3. Under "System assigned" tab, set Status to "On" > 4. Click "Save" > 5. Note the "Object (principal) ID" - this value is required for permission assignment > > **Via Azure CLI:** > > ```console theme={null} > # Enable system-assigned managed identity > az vm identity assign --name --resource-group > > # Get the principal ID > az vm identity show --name --resource-group --query principalId -o tsv > ``` > [tab] Azure Container Instance > > **Via Azure CLI:** > > ```console theme={null} > # Enable system-assigned managed identity > az container create \ > --resource-group \ > --name \ > --image \ > --assign-identity > > # Get the principal ID > az container show --resource-group --name --query identity.principalId -o tsv > ``` #### Step 2: Assign Reader Role to the Managed Identity The Managed Identity needs the **Reader** role on each subscription to scan. This role must be assigned to the **Managed Identity's principal ID**, not the VM or resource itself. > [tab] Azure Portal > > 1. Navigate to the **target subscription** to scan (not the VM's resource group) > > 2. Select "Access control (IAM)" from the left menu > > 3. Click "+ Add" > "Add role assignment" > > 4. Select "Reader" role, click "Next" > > 5. Click "+ Select members" > > 6. Search for the VM name or paste the Managed Identity's Object/Principal ID > > 7. Select it and click "Select" > > 8. Click "Review + assign" > > > [!NOTE] > > > > When scanning a subscription different from where the VM is located, ensure the role is assigned on the **target subscription**, not the VM's subscription. > [tab] Azure CLI > > ```console theme={null} > # Get the principal ID of the resource's managed identity > PRINCIPAL_ID=$(az vm identity show --name --resource-group --query principalId -o tsv) > > # Assign Reader role on the target subscription > az role assignment create \ > --role "Reader" \ > --assignee-object-id $PRINCIPAL_ID \ > --assignee-principal-type ServicePrincipal \ > --scope /subscriptions/ > ``` #### Step 3: Create and Assign ProwlerRole to the Managed Identity The ProwlerRole is a custom role required for specific security checks. First, create the role if it does not exist, then assign it to the Managed Identity. > [tab] Azure CLI > > **Create the ProwlerRole:** > > ```console theme={null} > az role definition create --role-definition '{ > "Name": "ProwlerRole", > "IsCustom": true, > "Description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.", > "AssignableScopes": ["/subscriptions/"], > "Actions": [ > "Microsoft.Web/sites/host/listkeys/action", > "Microsoft.Web/sites/config/list/Action" > ] > }' > ``` > > **Assign ProwlerRole to the Managed Identity:** > > ```console theme={null} > # Get the principal ID if not already available > PRINCIPAL_ID=$(az vm identity show --name --resource-group --query principalId -o tsv) > > # Assign ProwlerRole on the target subscription > az role assignment create \ > --role "ProwlerRole" \ > --assignee-object-id $PRINCIPAL_ID \ > --assignee-principal-type ServicePrincipal \ > --scope /subscriptions/ > ``` > [tab] Azure Portal > > Follow the same process as creating the ProwlerRole in the [Assigning ProwlerRole Permissions](/user-guide/providers/azure/authentication#assigning-prowlerrole-permissions-at-the-subscription-level) section, then assign it to the Managed Identity using the same steps as the Reader role assignment. #### Step 4: (Optional) Assign Microsoft Graph Permissions For Entra ID (Azure AD) checks, the Managed Identity needs Microsoft Graph API permissions: `Directory.Read.All`, `Policy.Read.All`, and `AuditLog.Read.All`. > [!NOTE] > > Assigning Microsoft Graph API permissions to a Managed Identity requires Azure CLI or PowerShell - it cannot be done through the Azure Portal's standard role assignment interface. ```console theme={null} # Get the Managed Identity's principal ID PRINCIPAL_ID=$(az vm identity show --name --resource-group --query principalId -o tsv) # Get Microsoft Graph's service principal ID GRAPH_SP_ID=$(az ad sp list --display-name "Microsoft Graph" --query [0].id -o tsv) # Assign Directory.Read.All permission (App Role ID: 7ab1d382-f21e-4acd-a863-ba3e13f7da61) az rest --method POST \ --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$PRINCIPAL_ID/appRoleAssignments" \ --headers "Content-Type=application/json" \ --body "{\"principalId\": \"$PRINCIPAL_ID\", \"resourceId\": \"$GRAPH_SP_ID\", \"appRoleId\": \"7ab1d382-f21e-4acd-a863-ba3e13f7da61\"}" # Assign Policy.Read.All permission (App Role ID: 246dd0d5-5bd0-4def-940b-0421030a5b68) az rest --method POST \ --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$PRINCIPAL_ID/appRoleAssignments" \ --headers "Content-Type=application/json" \ --body "{\"principalId\": \"$PRINCIPAL_ID\", \"resourceId\": \"$GRAPH_SP_ID\", \"appRoleId\": \"246dd0d5-5bd0-4def-940b-0421030a5b68\"}" ``` #### Step 5: Run Prowler SSH or connect to the Azure resource and run Prowler: ```console theme={null} # Scan all accessible subscriptions prowler azure --managed-identity-auth # Scan specific subscription(s) prowler azure --managed-identity-auth --subscription-ids ``` > [!NOTE] > > Wait a few minutes after assigning roles for Azure to propagate permissions. Role assignments are not always immediately effective. ### Troubleshooting #### Error: "No subscriptions were found, please check your permission assignments" **Cause:** The Managed Identity does not have the Reader role assigned on any subscription. **Solution:** * Verify the Managed Identity has the Reader role assigned on at least one subscription. * Wait a few minutes after role assignment for Azure to propagate permissions. * Verify role assignments: ```console theme={null} az role assignment list --assignee --all ``` #### Error: "does not have authorization to perform action 'Microsoft.Resources/subscriptions/read'" **Cause:** The Managed Identity lacks the Reader role on the target subscription. **Solution:** * Ensure the Reader role is assigned to the **Managed Identity's principal ID**, not the VM resource. * Verify the role is assigned on the **target subscription** to scan, not just the VM's resource group. * Check role assignments: ```console theme={null} az role assignment list --assignee --scope /subscriptions/ ``` #### Error: "CredentialUnavailableError: ManagedIdentityCredential authentication unavailable" **Cause:** Managed Identity is not enabled on the resource, or Prowler is running outside of Azure. **Solution:** * Verify Managed Identity is enabled on the Azure resource. * Ensure Prowler is running from within the Azure resource (not a local machine). * Check Managed Identity status: ```console theme={null} az vm identity show --name --resource-group ``` #### Error: Access token validation failure for Entra ID checks **Cause:** The Managed Identity lacks Microsoft Graph API permissions. **Solution:** * Assign the required Graph API permissions as shown in Step 4. * These permissions are optional for basic resource scanning but required for Entra ID security checks. ## Browser Authentication *Available only for Prowler CLI* Authenticate using the default browser: ```console theme={null} prowler azure --browser-auth --tenant-id ``` > **Note:** The `tenant-id` parameter is mandatory for browser authentication. # Creating a Prowler Service Principal Application Source: https://docs.prowler.com/user-guide/providers/azure/create-prowler-service-principal To enable Prowler to assume an identity for scanning with the required privileges, a Service Principal must be created. This Service Principal authenticates against Azure and retrieves necessary metadata for checks. Service Principal Applications can be created using either the Azure Portal or the Azure CLI. ![Registering an Application in Azure CLI for Prowler](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/prowler-app/create-sp.gif?s=066bccb7c389584554748847381ab208) ## Creating a Service Principal via Azure Portal / Entra Admin Center 1. Access **Microsoft Entra ID** in the [Azure Portal](https://portal.azure.com) ![Search Microsoft Entra ID](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/search-microsoft-entra-id.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=189236d8ad79b92948a8291726b2efca) 2. Navigate to "Manage" > "App registrations" ![App Registration nav](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/app-registration-menu.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=c2db94628ba5c10d7a59405bef539571) 3. Click "+ New registration", complete the form, and click "Register" ![New Registration](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/new-registration.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=0786c30207a713d75f6045d5b3ba0333) 4. Go to "Certificates & secrets" > "+ New client secret" ![Certificate & Secrets nav](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/certificates-and-secrets.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=01507142709ea0cfa1d047b6c9d5bb82) ![New Client Secret](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/new-client-secret.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=b4a8ec55604f77f7cba885f3b27a1b04) 5. Fill in the required fields and click "Add", then copy the generated value | Value | Description | | - | - | | Client ID | Application ID | | Client Secret | Secret to Connect to the App | | Tenant ID | Microsoft Entra Tenant ID | ## Creating a Service Principal from Azure CLI To create a Service Principal using the Azure CLI, follow these steps: 1. Open a terminal and execute the following command: ```console theme={null} az ad sp create-for-rbac --name "ProwlerApp" ``` 2. The output will be similar to: ```json theme={null} { "appId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "displayName": "ProwlerApp", "password": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "tenant": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" } ``` 3. Save the values of `appId`, `password` and `tenant`, as they will be used as credentials in Prowler. ## Assigning Proper Permissions Go to [Assigning Proper Permissions](/user-guide/providers/azure/authentication#required-permissions) to learn how to assign the necessary permissions to the Service Principal. # Getting Started With Azure on Prowler Source: https://docs.prowler.com/user-guide/providers/azure/getting-started-azure ## Prowler Cloud > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). [Prowler Cloud Onboarding Azure](https://www.youtube-nocookie.com/embed/v1as8vTFlMg) > Walkthrough video onboarding an Azure Subscription using Service Principal. > [!NOTE] > > **Government Cloud Support** > > Government cloud subscriptions (Azure Government) are not currently supported, but we expect to add support for them in the near future. ### Prerequisites Before setting up Azure in Prowler Cloud, you need to create a Service Principal with proper permissions. For detailed instructions on how to create the Service Principal and configure permissions, see [Authentication > Service Principal](/user-guide/providers/azure/authentication#service-principal-application-authentication-recommended). *** ### Step 1: Get the Subscription ID 1. Go to the [Azure Portal](https://portal.azure.com/#home) and search for `Subscriptions` 2. Locate and copy your Subscription ID ![Search Subscription](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/search-subscriptions.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=ff466bd9550a437073b061a84a7f5d3b) ![Subscriptions Page](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/get-subscription-id.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=673895ba44739db6079b027ffd1bab21) *** ### Step 2: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Navigate to `Configuration` > `Providers` ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click `Add Provider` ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select `Microsoft Azure` ![Select Microsoft Azure](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-azure-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=63d7995fa0567fc6b86b88a29faa5f28) 5. Add the Subscription ID and an optional alias, then click `Next` ![Add Subscription ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-subscription-id.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=af00e9c32ec0cbcb1d392ea6d968dc80) ### Step 3: Add Credentials to Prowler Cloud For Azure, Prowler Cloud uses a service principal application to authenticate. For more information about the process of creating and adding permissions to a service principal refer to this [section](/user-guide/providers/azure/authentication). When you finish creating and adding the [Entra](/user-guide/providers/azure/create-prowler-service-principal#assigning-proper-permissions) and [Subscription](/user-guide/providers/azure/subscriptions) scope permissions to the service principal, enter the `Tenant ID`, `Client ID` and `Client Secret` of the service principal application. 1. Go to your App Registration overview and copy the `Client ID` and `Tenant ID` ![App Overview](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/app-overview.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=586c4ae58f07515f0ffb7208379f5243) 2. Go to Prowler Cloud and paste: * `Client ID` * `Tenant ID` * `Client Secret` from [earlier](/user-guide/providers/azure/authentication#service-principal-application-authentication-recommended) ![Prowler Cloud Azure Credentials](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-credentials-azure-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=c9a24d693781b4d330d3f894809a4983) 3. Click `Next` ![Next Detail](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/click-next-azure.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=13d354023bd72f18e32c3fd3f235aebd) 4. Click "Launch Scan" ![Launch Scan Azure](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/launch-scan.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=ae7b5ac92f3198e4be067dfb2c1261bf) *** ## Prowler CLI ### Configure Azure Credentials To authenticate with Azure, Prowler CLI supports multiple authentication methods. Choose the method that best suits your environment. For detailed authentication setup instructions, see [Authentication](/user-guide/providers/azure/authentication). **Service Principal (Recommended)** Set up environment variables: ```console theme={null} export AZURE_CLIENT_ID="XXXXXXXXX" export AZURE_TENANT_ID="XXXXXXXXX" export AZURE_CLIENT_SECRET="XXXXXXX" ``` Then run: ```console theme={null} prowler azure --sp-env-auth ``` **Azure CLI Credentials** Use stored Azure CLI credentials: ```console theme={null} prowler azure --az-cli-auth ``` **Browser Authentication** Authenticate using your default browser: ```console theme={null} prowler azure --browser-auth --tenant-id ``` **Managed Identity** When running on Azure resources: ```console theme={null} prowler azure --managed-identity-auth ``` ### Subscription Selection To scan a specific Azure subscription: ```console theme={null} prowler azure --subscription-ids ``` To scan multiple Azure subscriptions: ```console theme={null} prowler azure --subscription-ids ``` # Azure Management Groups in Prowler Source: https://docs.prowler.com/user-guide/providers/azure/management-groups Azure Management Groups provide a hierarchy above subscriptions. They allow Azure role assignments and governance policies to apply to multiple subscriptions through a shared scope. For the cross-provider concepts and lifecycle, see [Organizations Across Cloud Providers](/user-guide/organizations). ## Azure Hierarchy Azure resources are organized in the following order: 1. Tenant 2. Management groups 3. Subscriptions 4. Resource groups 5. Resources Prowler scans Azure subscriptions. Management groups help organize those subscriptions and provide a scope where permissions can be assigned, but a management group is not itself a scan target. ## Create a Management Group To create a management group, follow the [official Azure guide](https://learn.microsoft.com/en-us/azure/governance/management-groups/create-management-group-portal). ![Create management group](https://mintcdn.com/prowler/LI3palQgXkn4dRXg/images/create-management-group.gif?s=65fc521124276c6ba22be67d5ce1f9f9) After creating the management group, add the subscriptions that Prowler should access and scan. ![Add Subscription to Management Group](https://mintcdn.com/prowler/su_yXbKgm6vDhiMb/images/add-sub-to-management-group.gif?s=a72fa426d10a21682618a5aef966b00b) ## Assign Roles Assign the roles required by Prowler at the management-group scope instead of assigning them separately to every subscription. Role assignments at a management group can inherit to its child subscriptions, subject to Azure role-assignment and inheritance rules. Use the [subscription scope permissions](/user-guide/providers/azure/authentication#subscription-scope-permissions) guide to identify the permissions required for scans. The identity used by Prowler must be able to read the management-group hierarchy and access each subscription selected for scanning. ## Subscription Scope Management groups organize subscriptions, but Azure scan results remain scoped to individual subscriptions: * Prowler Cloud scans one subscription per scan. * Prowler CLI can scan multiple subscriptions by using the `--subscription-ids` option. * A subscription must be accessible to the configured identity before Prowler can scan it. * Moving a subscription between management groups can change the permissions it inherits and may require a connection test or rediscovery. See [Azure Subscription Scope](/user-guide/providers/azure/subscriptions) for subscription selection and CLI options. ## Limitations * Management groups do not replace subscription providers in Prowler. * Azure role inheritance depends on the management-group hierarchy and the scope of each assignment; verify access on every subscription selected for scanning. * The Prowler Cloud workflow is designed around Azure management-group discovery and subscription onboarding. The Prowler CLI workflow still requires explicit subscription selection when restricting scans. * Changes to management-group membership or role assignments may not be reflected until the hierarchy is refreshed and access is tested again. # Azure Resource Group Scope Source: https://docs.prowler.com/user-guide/providers/azure/resource-groups Prowler supports narrowing security scans to specific resource groups within Azure subscriptions. This is useful when you want to audit only a subset of resources rather than scanning an entire subscription. By default, Prowler scans all resource groups it has permission to access. Passing `--azure-resource-group` limits the scan to only the specified resource groups across all accessible subscriptions. ## Configuring Resource Group Scoped Scans To restrict a scan to one or more resource groups, pass them as arguments using the `--azure-resource-group` flag: ```console theme={null} prowler azure --az-cli-auth --azure-resource-group ... ``` For example, to scan only `rg-production` and `rg-staging`: ```console theme={null} prowler azure --az-cli-auth --azure-resource-group rg-production rg-staging ``` This works with all supported authentication methods: ```console theme={null} # Service Principal prowler azure --sp-env-auth --azure-resource-group rg-production # Browser prowler azure --browser-auth --tenant-id --azure-resource-group rg-production # Managed Identity prowler azure --managed-identity-auth --azure-resource-group rg-production ``` ## How It Works When `--azure-resource-group` is provided, Prowler validates each specified resource group against all accessible subscriptions. A resource group is included in the scan if it exists in **at least one** subscription. * If a resource group is found in one or more subscriptions, it will be scanned in those subscriptions only. * If a resource group is **not found in any** subscription, Prowler logs a warning and skips it. * If **none** of the provided resource groups are found across any subscription, Prowler logs a warning and no resource group scoped checks will run. * Resource group names are matched case-insensitively, so `MyGroup` and `mygroup` are treated as the same group, mirroring Azure's own behavior. > [!WARNING] > > If `--azure-resource-group` is used, checks that apply to specific resources are limited to the relevant resource groups. But if checks that apply to tenant or subscription scope (identity, policy, or subscription-level configuration checks) are involved, then these checks will run in their natural scope. # Azure Subscription Scope Source: https://docs.prowler.com/user-guide/providers/azure/subscriptions Prowler performs security scans within the subscription scope in Azure. To execute checks, it requires appropriate permissions to access the subscription and retrieve necessary metadata. By default, Prowler operates multi-subscription, scanning all subscriptions it has permission to list. If permissions are granted for only a single subscription, Prowler will limit scans to that subscription. ## Configuring Specific Subscription Scans in Prowler Additionally, Prowler supports restricting scans to specific subscriptions by passing a set of subscription IDs as an input argument. To configure this limitation, use the appropriate command options: ```console theme={null} prowler azure --az-cli-auth --subscription-ids ... ``` Prowler allows you to specify one or more subscriptions for scanning (up to N), enabling flexible audit configurations. > [!WARNING] > > The multi-subscription feature is available only in the CLI. In Prowler Cloud, each scan is limited to a single subscription. ## Assigning Permissions for Subscription Scans Check the [Authentication > Subscription Scope Permissions](/user-guide/providers/azure/authentication#subscription-scope-permissions) guide for more information on how to assign permissions for subscription scans. ## Recommendation for Managing Multiple Subscriptions Scanning multiple subscriptions requires creating and assigning roles for each, which can be a time-consuming process. To streamline subscription management and auditing, use [Azure Management Groups](/user-guide/providers/azure/management-groups) to organize subscriptions and assign permissions collectively. # Using Non-Default Azure Regions Source: https://docs.prowler.com/user-guide/providers/azure/use-non-default-cloud Microsoft offers cloud environments that comply with regional regulations. These clouds are available for use based on your requirements. By default, Prowler utilizes the commercial `AzureCloud` environment. (To list all available Azure clouds, use `az cloud list --output table`). As of this documentation's publication, the following Azure clouds are available: * AzureCloud * AzureChinaCloud * AzureUSGovernment To change the default cloud, include the flag `--azure-region`. For example: ```console theme={null} prowler azure --az-cli-auth --azure-region AzureChinaCloud ``` # Cloudflare Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/cloudflare/authentication [Added in:  5.17.0](https://github.com/prowler-cloud/prowler/releases/tag/5.17.0) Prowler for Cloudflare supports two authentication methods, both available in Prowler Cloud and Prowler CLI: * [**API Token**](#api-token-recommended) (**Recommended**) — Scoped, least-privilege access to specific permissions and zones. * [**API Key and Email**](#api-key-and-email-legacy) (**Legacy**) — Global access to the entire account using the Global API Key. > [!WARNING] > > **Use only one authentication method at a time.** If both API Token and API Key + Email are set, Prowler uses the API Token and logs an error about the conflict. ## Required Permissions Prowler requires read-only access to Cloudflare accounts, zones, and developer platform resources. The following permissions must be configured when creating the API Token: | Resource | Permission | Access | Description | | - | - | - | - | | `Account` | `Account Settings` | `Read` | Required to list accounts, verify user identity, and read account members and 2FA enforcement | | `Account` | `Account API Tokens` | `Read` | Required to read account-owned API tokens (expiration, IP filtering, last use) | | `Account` | `Workers Scripts` | `Read` | Required to read Workers scripts, their settings, bindings, and `workers.dev` exposure | | `Account` | `Workers R2 Storage` | `Read` | Required to read R2 buckets, public `r2.dev` access, custom domains, and CORS policies | | `User` | `API Tokens` | `Read` | Optional. Required to read the authenticated user's own API tokens | | `Zone` | `Zone` | `Read` | Required to list zones | | `Zone` | `Zone Settings` | `Read` | Required to read zone security settings (SSL/TLS mode, TLS versions, HSTS, Always Use HTTPS, WAF, etc.) | | `Zone` | `DNS` | `Read` | Required to read DNS records (SPF, DMARC, DKIM, CAA) and DNSSEC status | | `Zone` | `SSL and Certificates` | `Read` | Required to read Universal SSL settings | | `Zone` | `Bot Management` | `Read` | Required to read Bot Fight Mode | | `Zone` | `Zone WAF` | `Read` | Required to read WAF custom, rate limiting, and managed rulesets | > [!WARNING] > > Ensure the API Token has access to all zones targeted for scanning. Missing permissions may cause some checks to fail or return incomplete results. > [!NOTE] > > Account-owned API tokens can only be listed by tokens created by a Super Administrator. When a permission is missing, the affected checks report one `MANUAL` finding per account naming the missing permission, and the rest of the scan continues. User-owned tokens are still evaluated when the optional `API Tokens Read` user permission is granted. *** ## API Token (Recommended) User API Tokens are the recommended authentication method because they: * Can be scoped to specific permissions and zones * Are more secure than global API keys * Can be easily rotated without affecting other integrations > [!NOTE] > > Create a **User API Token**, not an Account API Token. User API Tokens are created from the profile settings and offer finer permission control. **Quick Setup:** Use these pre-configured links to open the Cloudflare Dashboard with most of the required permissions already selected. Add the `Account API Tokens`, `Workers Scripts`, and `Workers R2 Storage` read permissions manually before creating the token: * [Create User API Token](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22ssl_and_certificates%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22bot_management%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_waf%22%2C%22type%22%3A%22read%22%7D%5D\&accountId=%2A\&zoneId=all\&name=Prowler%20Security%20Scanner) — creates a **User API Token** (recommended). Opens the **Create Custom Token** form prefilled with the seven required read-only scopes (`Account Settings`, `Zone`, `Zone Settings`, `DNS`, `SSL and Certificates`, `Bot Management`, `Zone WAF`) and the name `Prowler Security Scanner`. Then add the `Account API Tokens`, `Workers Scripts`, and `Workers R2 Storage` read permissions (and optionally the user `API Tokens` read permission) manually. Adjust **Account Resources** and **Zone Resources** to match the accounts and zones you want to scan, then click **Create Token**. * [Create Account-Owned API Token](https://dash.cloudflare.com/?to=/:account/api-tokens\&permissionGroupKeys=%5B%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22ssl_and_certificates%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22bot_management%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_waf%22%2C%22type%22%3A%22read%22%7D%5D\&name=Prowler%20Security%20Scanner) — creates an [account-owned token](https://developers.cloudflare.com/fundamentals/api/how-to/account-owned-token-template/) instead. Use this for automation or CI/CD where the token should not depend on a specific user account remaining active. Requires the **Super Administrator** or **Administrator** role on the account. As with the user token link, add the `Account API Tokens`, `Workers Scripts`, and `Workers R2 Storage` read permissions manually. > [!NOTE] > > Template URLs only pre-fill the token creation form. Review the permissions, configure resources, and click **Create Token** to complete the process. ### Step 1: Create a User API Token 1. Log into the [Cloudflare Dashboard](https://dash.cloudflare.com). 2. Click the profile icon in the top right corner, then select "My Profile". 3. Click the **API Tokens** tab. 4. Click **Create Token**, then select **Create Custom Token** at the bottom of the page. 5. Configure the token with the following settings: * **Token name:** A descriptive name (e.g., "Prowler Security Scanner") * **Permissions:** * `Account` — `Account Settings` — `Read` * `Account` — `Account API Tokens` — `Read` * `Account` — `Workers Scripts` — `Read` * `Account` — `Workers R2 Storage` — `Read` * `User` — `API Tokens` — `Read` (optional, for user token checks) * `Zone` — `Zone` — `Read` * `Zone` — `Zone Settings` — `Read` * `Zone` — `DNS` — `Read` * `Zone` — `SSL and Certificates` — `Read` * `Zone` — `Bot Management` — `Read` * `Zone` — `Zone WAF` — `Read` * **Zone Resources:** Select either: * **Include → All zones** (to scan all zones in the account) * **Include → Specific zone** (to limit access to specific zones) ![Token Permissions](https://mintcdn.com/prowler/bGwwauGu6U19YOis/images/providers/cloudflare-token-permissions.png?fit=max\&auto=format\&n=bGwwauGu6U19YOis\&q=85\&s=24302023645232bcb580e17b1bc6b456) 6. Configure the **Account Resources** and **Zone Resources**, and optionally set a **TTL** for the token expiration. Click **Continue to summary**. ![Token Resources and TTL](https://mintcdn.com/prowler/B9BMXcFVIfrS7O9F/images/providers/cloudflare-token-save.png?fit=max\&auto=format\&n=B9BMXcFVIfrS7O9F\&q=85\&s=ddcdf99062020b09d4529d4e0201e9a4) 7. Review the permissions and click **Create Token**. 8. Copy the token immediately. > [!WARNING] > > Cloudflare only displays the token once. Copy it immediately and store it securely. If lost, a new token must be created. ### Step 2: Provide the Token to Prowler * **Prowler Cloud:** Paste the token in the credentials form when configuring the Cloudflare provider. * **Prowler CLI:** Export the token as an environment variable: ```console theme={null} export CLOUDFLARE_API_TOKEN="your-api-token-here" prowler cloudflare ``` *** ## API Key and Email (Legacy) API Keys provide full access to the Cloudflare account. While supported, this method is less secure than API Tokens because it grants broader permissions. ### Step 1: Get the Global API Key 1. Log into the [Cloudflare Dashboard](https://dash.cloudflare.com). 2. Click the profile icon in the top right corner, then select "My Profile". 3. Click the **API Tokens** tab. 4. Scroll down to the **API Keys** section. 5. Click **View** next to **Global API Key**. 6. Enter the account password to reveal the key, then copy it. ### Step 2: Provide the Credentials to Prowler * **Prowler Cloud:** Enter the Global API Key and email in the credentials form when configuring the Cloudflare provider. * **Prowler CLI:** Export both values as environment variables: ```console theme={null} export CLOUDFLARE_API_KEY="your-api-key-here" export CLOUDFLARE_API_EMAIL="your-email@example.com" prowler cloudflare ``` > [!NOTE] > > The email must match the email address used to log into the Cloudflare account. *** ## Best Practices * **Use API Tokens instead of API Keys** — Tokens can be scoped to specific permissions and zones. * **Use environment variables** — Never hardcode credentials in scripts or commands. * **Rotate credentials regularly** — Create new tokens periodically and revoke old ones. * **Use least privilege** — Only grant the minimum permissions needed for scanning. * **Monitor token usage** — Review the Cloudflare audit log for suspicious activity. *** ## Troubleshooting ### "Missing X-Auth-Email header" Error This error occurs when using API Key authentication without providing the email address. Ensure both `CLOUDFLARE_API_KEY` and `CLOUDFLARE_API_EMAIL` are set. ### "Authentication error" or "Permission denied" * Verify the API Token or API Key is correct and not expired. * Check that the token has the [required permissions](#required-permissions). * Ensure the token has access to the zones targeted for scanning. ### "Both API Token and API Key and Email credentials are set" This warning appears when all three environment variables are set (`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_API_KEY`, `CLOUDFLARE_API_EMAIL`). To resolve, unset the credentials that are not needed: ```console theme={null} # To use API Token only (recommended) unset CLOUDFLARE_API_KEY unset CLOUDFLARE_API_EMAIL # Or to use API Key and Email only unset CLOUDFLARE_API_TOKEN ``` ### "Account not found" Error This error occurs when a specified `--account-id` is not accessible with the current credentials. Verify the Account ID is correct and that the credentials have access to the target account. # Getting Started With Cloudflare on Prowler Source: https://docs.prowler.com/user-guide/providers/cloudflare/getting-started-cloudflare Prowler for Cloudflare scans zones for security misconfigurations, including SSL/TLS settings, DNSSEC, HSTS, WAF rules, DNS records, and more. ## Prerequisites Set up authentication for Cloudflare with the [Cloudflare Authentication](/user-guide/providers/cloudflare/authentication) guide before starting either path: * Create a Cloudflare User API Token (recommended) or locate the Global API Key * Grant the required read-only permissions (`Account Settings:Read`, `Account API Tokens:Read`, `Workers Scripts:Read`, `Workers R2 Storage:Read`, `Zone:Read`, `Zone Settings:Read`, `DNS:Read`, `SSL and Certificates:Read`, `Bot Management:Read`, `Zone WAF:Read`) * Identify the Cloudflare Account ID to use as the provider identifier > [!NOTE] > > **Quick Setup:** Use these pre-configured links to create a token with most of the required permissions already selected: > > * [Create User API Token](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22ssl_and_certificates%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22bot_management%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_waf%22%2C%22type%22%3A%22read%22%7D%5D\&accountId=%2A\&zoneId=all\&name=Prowler%20Security%20Scanner) — creates a User API Token (recommended). > * [Create Account-Owned API Token](https://dash.cloudflare.com/?to=/:account/api-tokens\&permissionGroupKeys=%5B%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22ssl_and_certificates%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22bot_management%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22zone_waf%22%2C%22type%22%3A%22read%22%7D%5D\&name=Prowler%20Security%20Scanner) — creates an [account-owned token](https://developers.cloudflare.com/fundamentals/api/how-to/account-owned-token-template/), better suited for automation and CI/CD. > > Both links open the Cloudflare Dashboard with the seven required read-only scopes (`Account Settings`, `Zone`, `Zone Settings`, `DNS`, `SSL and Certificates`, `Bot Management`, `Zone WAF`) and the name `Prowler Security Scanner` prefilled. Add the `Account API Tokens`, `Workers Scripts`, and `Workers R2 Storage` read permissions manually before creating the token. See [Cloudflare Authentication](/user-guide/providers/cloudflare/authentication#api-token-recommended) for the equivalent manual steps. > [card] [Prowler Cloud](#prowler-cloud) > > Onboard Cloudflare using Prowler Cloud > [card] [Prowler CLI](#prowler-cli) > > Onboard Cloudflare using Prowler CLI ## Prowler Cloud [Added in:  5.19.0](https://github.com/prowler-cloud/prowler/releases/tag/5.19.0) > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Step 1: Locate the Account ID 1. Log into the [Cloudflare Dashboard](https://dash.cloudflare.com). 2. Select any zone in the target account. 3. On the zone overview page, find the **Account ID** in the right sidebar under the "API" section. ![Cloudflare Account ID](https://mintcdn.com/prowler/B9BMXcFVIfrS7O9F/images/providers/cloudflare-account-id.png?fit=max\&auto=format\&n=B9BMXcFVIfrS7O9F\&q=85\&s=cc4d6afb6770ba2af14c7ab10d6af6fe) > [!NOTE] > > The Account ID is a 32-character hexadecimal string (e.g., `372e67954025e0ba6aaa6d586b9e0b59`). This value acts as the unique identifier for the Cloudflare account in Prowler Cloud. ### Step 2: Open Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up). 2. Navigate to "Configuration" > "Providers". ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider". ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Cloudflare". ![Select Cloudflare](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-cloudflare-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=f8bc0388b16f3e6dbe537e95729b77e8) 5. Add the **Account ID** and an optional alias, then click "Next". ![Add Cloudflare Account ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/cloudflare-account-id-form.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=883d94237b36c5b623e95bf765f501be) ### Step 3: Choose and Provide Authentication After the Account ID is in place, select the authentication method that matches the Cloudflare setup: ![Select Authentication Method](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/cloudflare-auth-selection.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=21ff00bbcbcdce10bc83cc5b79dd5058) #### User API Token Authentication (Recommended) 1. Select **API Token**. 2. Enter the **User API Token** created in the Cloudflare Dashboard. ![API Token Form](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/cloudflare-token-form.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=94b169349950524c8985cb756db03fad) Use this method for scoped, least-privilege access. Full setup steps are in the [Authentication guide](/user-guide/providers/cloudflare/authentication#api-token-recommended). #### API Key and Email Authentication (Legacy) 1. Select **API Key + Email**. 2. Enter the **Global API Key**. 3. Enter the **email address** associated with the Cloudflare account. ![API Key and Email Form](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/cloudflare-api-email-form.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=5168f8fc37dd0449663b0d8d5bc45339) For the complete setup workflow, follow the [Authentication guide](/user-guide/providers/cloudflare/authentication#api-key-and-email-legacy). ### Step 4: Launch the Scan 1. Review the summary. 2. Click **Launch Scan** to start auditing Cloudflare. ![Launch Scan](https://mintcdn.com/prowler/B9BMXcFVIfrS7O9F/images/providers/cloudflare-launch-scan.png?fit=max\&auto=format\&n=B9BMXcFVIfrS7O9F\&q=85\&s=413952427d4100fc66ccf03387129800) *** ## Prowler CLI [Added in:  5.17.0](https://github.com/prowler-cloud/prowler/releases/tag/5.17.0) ### Step 1: Set Up Authentication Choose the matching method from the [Cloudflare Authentication](/user-guide/providers/cloudflare/authentication) guide: * **User API Token** (recommended): Set `CLOUDFLARE_API_TOKEN` * **API Key + Email** (legacy): Set `CLOUDFLARE_API_KEY` and `CLOUDFLARE_API_EMAIL` ### Step 2: Run the First Scan Run a baseline scan after credentials are configured: ```console theme={null} prowler cloudflare ``` Prowler automatically discovers all zones accessible with the provided credentials and runs security checks against them. ### Step 3: Filter the Scan Scope (Optional) #### Filter by Zone To scan only specific zones, use the `-f`, `--region`, or `--filter-region` argument: ```console theme={null} prowler cloudflare -f example.com ``` Multiple zones can be specified: ```console theme={null} prowler cloudflare -f example.com example.org ``` Zone IDs are also supported: ```console theme={null} prowler cloudflare -f 023e105f4ecef8ad9ca31a8372d0c353 ``` #### Filter by Account To restrict the scan to specific accounts, use the `--account-id` argument: ```console theme={null} prowler cloudflare --account-id 372e67954025e0ba6aaa6d586b9e0b59 ``` Multiple account IDs can be specified: ```console theme={null} prowler cloudflare --account-id 372e67954025e0ba6aaa6d586b9e0b59 9a7806061c88ada191ed06f989cc3dac ``` > [!NOTE] > > If any of the provided account IDs are not accessible with the current credentials, Prowler raises an error and stops execution. Account and zone filtering can be combined to narrow the scan scope further: ```console theme={null} prowler cloudflare --account-id 372e67954025e0ba6aaa6d586b9e0b59 -f example.com ``` ### Step 4: Use a Custom Configuration (Optional) Prowler uses a configuration file to customize provider behavior. The Cloudflare configuration includes: ```yaml theme={null} cloudflare: # Maximum number of retries for API requests (default is 2) max_retries: 2 ``` To use a custom configuration: ```console theme={null} prowler cloudflare --config-file /path/to/config.yaml ``` *** # E2E Networks Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/e2enetworks/authentication [Added in:  5.34.0](https://github.com/prowler-cloud/prowler/releases/tag/5.34.0) Prowler for E2E Networks authenticates against the E2E Networks MyAccount API using an **API key**, an **auth token**, and a numeric **project ID**. Set the API key and auth token as environment variables to avoid exposing secrets in shell history or process listings. Compatibility CLI flags are still accepted, but Prowler warns when secret values are passed directly on the command line. ## Required Credentials Prowler requires read access to the E2E Networks project. The following values are needed: | Credential | Environment Variable | Description | | - | - | - | | API Key | `E2E_NETWORKS_API_KEY` | Identifies the MyAccount API key used for requests | | Auth Token | `E2E_NETWORKS_AUTH_TOKEN` | Bearer token authorizing the API key | | Project ID | `E2E_NETWORKS_PROJECT_ID` | Numeric ID of the project to scan | | Region | `E2E_NETWORKS_REGION` | Optional region to scan (defaults to all regions: Delhi, Chennai) | > [!WARNING] > > The project ID must be an integer. A missing or non-numeric project ID stops the scan before any resource is read. *** ## API Credentials ### Step 1: Create the API Key and Auth Token 1. Log into the [E2E Networks MyAccount portal](https://myaccount.e2enetworks.com). 2. Open the **API Tokens** section under the account settings. 3. Create a new API token and copy both the API key and the auth token. 4. Copy the values immediately — the auth token is not shown again. ### Step 2: Find the Project ID Select the target project in MyAccount and copy its numeric project ID from the project settings or the API context. ### Step 3: Configure Authentication Export the credentials as environment variables: ```bash theme={null} export E2E_NETWORKS_API_KEY="your-api-key" export E2E_NETWORKS_AUTH_TOKEN="your-auth-token" export E2E_NETWORKS_PROJECT_ID="your-project-id" ``` Then run Prowler: ```bash theme={null} prowler e2enetworks ``` *** ## Verifying Authentication To confirm that Prowler can reach the E2E Networks project, run a scan against a single location: ```bash theme={null} prowler e2enetworks --region Delhi ``` A successful run reports findings for the discovered resources. A failed run displays an error message indicating the credential or connectivity issue. *** ## CI/CD Integration For automated pipelines, set the credentials as secret environment variables: **GitHub Actions:** ```yaml theme={null} env: E2E_NETWORKS_API_KEY: ${{ secrets.E2E_NETWORKS_API_KEY }} E2E_NETWORKS_AUTH_TOKEN: ${{ secrets.E2E_NETWORKS_AUTH_TOKEN }} E2E_NETWORKS_PROJECT_ID: ${{ secrets.E2E_NETWORKS_PROJECT_ID }} steps: - name: Run Prowler run: prowler e2enetworks ``` **GitLab CI:** ```yaml theme={null} variables: E2E_NETWORKS_API_KEY: $E2E_NETWORKS_API_KEY E2E_NETWORKS_AUTH_TOKEN: $E2E_NETWORKS_AUTH_TOKEN E2E_NETWORKS_PROJECT_ID: $E2E_NETWORKS_PROJECT_ID prowler_scan: script: - prowler e2enetworks ``` # Getting Started With E2E Networks on Prowler Source: https://docs.prowler.com/user-guide/providers/e2enetworks/getting-started-e2enetworks [Added in:  5.34.0](https://github.com/prowler-cloud/prowler/releases/tag/5.34.0) Prowler for E2E Networks scans E2E Networks infrastructure for security misconfigurations across compute nodes, networking, security groups, load balancers, storage, and managed databases. > [!NOTE] > > E2E Networks support in Prowler is community-maintained. For commercial support or to request additional service coverage, [contact us](https://prowler.com/contact). ## Prerequisites Set up authentication for E2E Networks with the [E2E Networks Authentication](/user-guide/providers/e2enetworks/authentication) guide before starting: * Create an E2E Networks API key and auth token from the MyAccount API Tokens section * Note the numeric project ID of the project to scan ## Prowler CLI ### Run Prowler for E2E Networks Once authenticated, export the credentials as environment variables and run Prowler for E2E Networks. Environment variables keep secrets out of shell history and process listings: ```bash theme={null} export E2E_NETWORKS_API_KEY="your-api-key" export E2E_NETWORKS_AUTH_TOKEN="your-auth-token" export E2E_NETWORKS_PROJECT_ID="your-project-id" prowler e2enetworks ``` ### Run Specific Checks ```bash theme={null} prowler e2enetworks --checks node_encryption_enabled storage_block_volume_not_orphaned ``` ### Run a Specific Service ```bash theme={null} prowler e2enetworks --services node ``` ### Scan Specific Regions Use `--region` (aliases `--filter-region` and `-f`) to limit the scan to one or more E2E Networks regions. When the flag is omitted, Prowler reads `E2E_NETWORKS_REGION` and otherwise scans all regions (Delhi, Chennai). ```bash theme={null} prowler e2enetworks --region Delhi Chennai ``` ## Available Services Prowler for E2E Networks currently supports the following services: | Service | Description | | - | - | | `database` | Managed database clusters and their backup, network, and encryption settings | | `loadbalancer` | Application load balancers and their TLS, health-check, and protection settings | | `network` | Virtual Private Clouds, peering, and reserved public IP addresses | | `node` | Compute nodes and their encryption, protection, and network configuration | | `securitygroup` | Security groups and their inbound and default traffic rules | | `storage` | Block volumes and file storage (EFS/EPFS) with their protection settings | # GCP Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/gcp/authentication Prowler for Google Cloud supports multiple authentication methods. To use a specific method, configure the appropriate credentials during execution: * [**User Credentials** (Application Default Credentials)](#application-default-credentials-user-credentials) * [**Service Account Key File**](#service-account-key-file) * [**Access Token**](#access-token) * [**Service Account Impersonation**](#service-account-impersonation) ## Required Permissions Prowler for Google Cloud requires the following permissions: ### IAM Roles * **Viewer (`roles/viewer`)** – Must be granted at the **project, folder, or organization** level to allow scanning of target projects. * **Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`)** IAM Role – Required for resource scanning. * **Custom `ProwlerRole`** – Include granular permissions that are not included in the Viewer role: * `storage.buckets.getIamPolicy` ### Project-Level Settings At least one project must have the following configurations: * **Identity and Access Management (IAM) API (`iam.googleapis.com`)** – Must be enabled via: * The [Google Cloud API UI](https://console.cloud.google.com/apis/api/iam.googleapis.com/metrics), or * The `gcloud` CLI: ```sh theme={null} gcloud services enable iam.googleapis.com --project ``` * **Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`)** IAM Role – Required for resource scanning. * **Quota Project Setting** – Define a quota project using either: * The `gcloud` CLI: ```sh theme={null} gcloud auth application-default set-quota-project ``` * Setting an environment variable: ```sh theme={null} export GOOGLE_CLOUD_QUOTA_PROJECT= ``` > [!NOTE] > > Prowler will scan the GCP project associated with the credentials. ## Application Default Credentials (User Credentials) This method uses the Google Cloud CLI to authenticate and is suitable for development and testing environments. ### Setup Application Default Credentials 1. In the [GCP Console](https://console.cloud.google.com/), click "Activate Cloud Shell" ![Activate Cloud Shell](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/access-console.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=96b905aa355ba3bbe33d8fc47562c58b) 2. Click "Authorize Cloud Shell" ![Authorize Cloud Shell](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/authorize-cloud-shell.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=5d099746aaa1179d8c6e7e80d3eb9ff7) 3. Run the following command: ```bash theme={null} gcloud auth application-default login ``` * Type `Y` when prompted ![Run Gcloud Auth](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/run-gcloud-auth.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=ee345c02976cfba0f2777fddc09977f3) 4. Open the authentication URL provided in a browser and select your Google account ![Choose the account](https://mintcdn.com/prowler/cmPhg0PQUNFwgauQ/images/providers/take-account-email.png?fit=max\&auto=format\&n=cmPhg0PQUNFwgauQ\&q=85\&s=51f26697b050e45ed109d7de49540b3d) 5. Follow the steps to obtain the authentication code ![Copy auth code](https://mintcdn.com/prowler/VEKBBm2VL7R8-xYV/images/providers/copy-auth-code.png?fit=max\&auto=format\&n=VEKBBm2VL7R8-xYV\&q=85\&s=7dc5ffe2d519351d009ead0198a3091f) 6. Paste the authentication code back in Cloud Shell ![Enter Auth Code](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/enter-auth-code.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=bb6a39f186d02de52c493c12b9ddb9bc) 7. Use `cat ` to view the temporary credentials file ![Get the FileName](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/get-temp-file-credentials.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=6ce807441c7a100639b7de0ab9fb3719) 8. Extract the following values for Prowler Cloud: * `client_id` * `client_secret` * `refresh_token` ![Get the values](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/get-needed-values-auth.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=710bc8e49b678b80c2f3d41fbbede99d) ### Using with Prowler CLI Once application default credentials are set up, run Prowler directly: ```console theme={null} prowler gcp --project-ids ``` ## Service Account Key File This method uses a service account with a downloaded key file for authentication. ### Step 1: Create ProwlerRole To keep permissions focused: 1. Create a custom role named **ProwlerRole** that explicitly includes the permissions your compliance team approves. Click **Create role**, set the title to *ProwlerRole*, keep the ID readable (for example, `prowler_role`) 2. Add the required permission `storage.buckets.getIamPolicy` (the permission highlighted in the screenshots). To make it easier, filter the permissions by `Storage Admin` role. ![Create a custom Prowler role](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/roles-section.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=08cb05c799de17320974f83ff422cd48) ![Sample permissions for a custom Prowler role](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/prowler-role.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=e90127867d19b5032691adf76ca03de1) ### Step 2: Create the Service Account 1. Navigate to **IAM & Admin > Service Accounts** and make sure the correct project is selected. ![Service accounts landing page](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/service-account-page.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=4c1836e3b6d4574d46960d7f7d5f4f0c) 2. Select **Create service account**, provide a name, ID, and a short description that states the purpose (for example, “Service account to execute Prowler”), then click **Create and continue**. ![Create service account wizard](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/create-service-account.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=e9780e84c1276b11f398b0e4678f3a03) 3. Assign the roles you prepared earlier: * **ProwlerRole** for `cloudstorage` service checks. * **Viewer** for broad read-only visibility. * **Service Usage Consumer** so Prowler can inspect API states. ![Assign roles to the service account](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/service-account-permissions.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=a5f3ea4bb08236020cb54d59d52322c0) 4. Continue through the wizard and finish. No principals need to be granted access in step 3 unless you want other identities to impersonate this account. > [!NOTE] > > To use this service account with `--organization-id`, additionally grant `roles/cloudasset.viewer` at the organization node and enable the Cloud Asset API in the service account's host project. See [Scanning a Specific GCP Organization](./organization). Without these, organization-wide scans silently fall back to listing only the projects accessible to the service account. ### Step 3: Generate a JSON Key 1. Open the newly created service account, move to the **Keys** tab, and choose **Add key > Create new key**. ![Add a new key to the service account](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/create-new-key.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=188edf94362e7beca95bc773ccf0def5) 2. Select **JSON** as the key type and click **Create**. The browser downloads the file exactly once. ![Select JSON as the key type](https://mintcdn.com/prowler/R3TgzvrQGHAsWrK1/user-guide/providers/gcp/img/json-key.png?fit=max\&auto=format\&n=R3TgzvrQGHAsWrK1\&q=85\&s=7535e9b7a850419939fc079c2670906a) 3. Once created, make sure to store the Key securely. ### Using with Prowler CLI Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable: ```console theme={null} export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json" prowler gcp --project-ids ``` ## Access Token For existing access tokens (e.g., generated with `gcloud auth print-access-token`), run Prowler with: ```bash theme={null} export CLOUDSDK_AUTH_ACCESS_TOKEN=$(gcloud auth print-access-token) prowler gcp --project-ids ``` > [!NOTE] > > When using this method, also set the default project explicitly: > > ```bash theme={null} > export GOOGLE_CLOUD_PROJECT= > ``` ## Service Account Impersonation To impersonate a GCP service account, use the `--impersonate-service-account` argument followed by the service account email: ```console theme={null} prowler gcp --impersonate-service-account ``` This command leverages the default credentials to impersonate the specified service account. ### Prerequisites for Impersonation The identity running Prowler must have the following permission on the target service account: * `roles/iam.serviceAccountTokenCreator` Or the more specific permission: * `iam.serviceAccounts.generateAccessToken` # Getting Started With GCP on Prowler Source: https://docs.prowler.com/user-guide/providers/gcp/getting-started-gcp ## Prowler Cloud > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Step 1: Get the GCP Project ID 1. Go to the [GCP Console](https://console.cloud.google.com/) 2. Locate the Project ID on the welcome screen ![Get the Project ID](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/project-id-console.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=78a38e19d11436ec99293ed12f5a11b8) ### Step 2: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Go to "Configuration" > "Providers" ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider" ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Google Cloud Platform" ![Select GCP](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-gcp.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=73eb18d002c81cf4d36c0a399dba22bb) 5. Add the Project ID and optionally provide a provider alias, then click "Next" ![Add Project ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-project-id.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=d0e120e98f222ca23af75969dd219bbd) ### Step 3: Set Up GCP Authentication For Google Cloud, first enter your `GCP Project ID` and then select the authentication method you want to use: * **Service Account Authentication** (**Recommended**) * Authenticates as a service identity * Stable and auditable * Recommended for production * **Application Default Credentials** * Quick scan as current user * Uses Google Cloud CLI authentication * Credentials may time out **Service Account Authentication** is the recommended authentication method for automated systems and machine-to-machine interactions, like Prowler. For detailed information about this, refer to the [Google Cloud documentation](https://cloud.google.com/iam/docs/service-account-overview). ![GCP Authentication Methods](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/gcp-auth-methods.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=dee2972c8d7622832a91b5df8b118070) > [tab] Service Account Authentication > > First of all, in the same project that you selected in the previous step, you need to create a service account and then generate a key in JSON format for it. For more information about this, you can follow the next Google Cloud documentation tutorials: > > * [Create a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) > * [Generate a key for a service account](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) > > ![GCP Service Account Credentials](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/gcp-service-account-creds.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=5acbf877d3e3a04146ca59ed8eda30c1) > > For detailed instructions on how to setup Service Account authentication, see the [Authentication](/user-guide/providers/gcp/authentication#service-account-authentication) page. > [tab] Application Default Credentials > > 1. Run the following command in your terminal to authenticate with GCP: > > ```bash theme={null} > gcloud auth application-default login > ``` > > 2. Once authenticated, get the `Client ID`, `Client Secret` and `Refresh Token` from `~/.config/gcloud/application_default_credentials`. > > 3. Paste the `Client ID`, `Client Secret` and `Refresh Token` into Prowler Cloud. > > ![GCP Credentials](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/gcp-credentials.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=a97b3c115ef26fd72581b8d593839cdc) 7. Click "Next", then "Launch Scan" ![Launch Scan GCP](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/user-guide/providers/gcp/img/launch-scan.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=778fcdff303bde34d668ce135417107e) *** ## Prowler CLI ### Credentials Lookup Order Prowler follows the same credential search process as [Google authentication libraries](https://cloud.google.com/docs/authentication/application-default-credentials#search_order), checking credentials in this order: 1. [`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/application-default-credentials#GAC) 2. [`CLOUDSDK_AUTH_ACCESS_TOKEN` + optional `GOOGLE_CLOUD_PROJECT`](https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token) 3. [User credentials set up by using the Google Cloud CLI](https://cloud.google.com/docs/authentication/application-default-credentials#personal) 4. [Attached service account (e.g., Cloud Run, GCE, Cloud Functions)](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa) > [!NOTE] > > The credentials must belong to a user or service account with the necessary permissions. > For detailed instructions on how to set the permissions, see [Authentication > Required Permissions](/user-guide/providers/gcp/authentication#required-permissions). > [!NOTE] > > Prowler will use the enabled Google Cloud APIs to get the information needed to perform the checks. ### Configure GCP Credentials To authenticate with GCP, use one of the following methods: ```console theme={null} gcloud auth application-default login ``` or set the credentials file path: ```console theme={null} export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json" ``` These credentials must belong to a user or service account with the necessary permissions to perform security checks. For more authentication details, see the [Authentication](/user-guide/providers/gcp/authentication) page. ### Project Specification To scan specific projects, specify them with the following command: ```console theme={null} prowler gcp --project-ids ``` ### Service Account Impersonation For service account impersonation, use the `--impersonate-service-account` flag: ```console theme={null} prowler gcp --impersonate-service-account ``` More details on authentication methods in the [Authentication](/user-guide/providers/gcp/authentication) page. ### Skip API Check By default, Prowler verifies which Google Cloud APIs are enabled before running checks for each service. To skip this verification and assume all APIs are active, use the `--skip-api-check` flag: ```console theme={null} prowler gcp --skip-api-check ``` > [!NOTE] > > This is useful when the authenticated principal lacks the `serviceusage.services.list` permission but has access to individual service APIs. # Scanning a Specific GCP Organization Source: https://docs.prowler.com/user-guide/providers/gcp/organization By default, Prowler scans all Google Cloud projects accessible to the authenticated user. For the cross-provider organization lifecycle and capability comparison, see [Organizations Across Cloud Providers](/user-guide/organizations). To limit the scan to projects within a specific Google Cloud organization, use the `--organization-id` option with the GCP organization’s ID: ```console theme={null} prowler gcp --organization-id organization-id ``` > [!WARNING] > > Ensure the credentials used have one of the following roles bound **at the organization node** (not at a project): Cloud Asset Viewer (`roles/cloudasset.viewer`) or Cloud Asset Owner (`roles/cloudasset.owner`). The role must be bound directly on the organization so the Cloud Asset API can enumerate projects across the whole hierarchy. > > ```bash theme={null} > gcloud organizations add-iam-policy-binding \ > --member="serviceAccount:" \ > --role="roles/cloudasset.viewer" > ``` > > The Cloud Asset API (`cloudasset.googleapis.com`) must also be enabled in the project that owns the credentials (the service account's host project, or the quota project for user credentials): > > ```bash theme={null} > gcloud services enable cloudasset.googleapis.com --project > ``` > [!NOTE] > > With this option, Prowler retrieves all projects under the specified Google Cloud organization, including those organized within folders and nested subfolders. This ensures full visibility across the entire organization’s hierarchy. > [!NOTE] > > To obtain the Google Cloud organization ID, use: > > ```console theme={null} > gcloud organizations list > ``` # GCP Project Scanning in Prowler Source: https://docs.prowler.com/user-guide/providers/gcp/projects By default, Prowler operates in a multi-project mode, scanning all Google Cloud projects accessible to the authenticated user. ## Specifying Projects To limit the scan to specific projects, use the `--project-ids` argument followed by the desired project ID(s). ```console theme={null} prowler gcp --project-ids project-id1 project-id2 ``` ### Pattern-Based Project Selection Use an asterisk `*` to scan projects that match a pattern. For example, `prowler gcp --project-ids "prowler*"` will scan all the projects that start with `prowler`. ### Listing Accessible Projects To view a list of projects the user has access to, run: ```console theme={null} prowler gcp --list-project-ids ``` ### Excluding Projects in Prowler #### Project Exclusion To exclude specific Google Cloud projects from the scan, use the `--excluded-project-ids` argument followed by the project ID(s): ```console theme={null} prowler gcp --excluded-project-ids project-id1 project-id2 ``` #### Pattern-Based Project Exclusion Use an asterisk `*` to exclude projects that match a pattern. For example, `prowler gcp --excluded-project-ids "sys*"` will exclude all the projects that start with `sys`. # GCP Retry Configuration in Prowler Source: https://docs.prowler.com/user-guide/providers/gcp/retry-configuration Prowler's GCP Provider uses Google Cloud Python SDK's integrated retry mechanism to automatically retry API calls when encountering rate limiting errors (HTTP 429). ## Quick Configuration ### Using Command Line Flag (Recommended) ```bash theme={null} prowler gcp --gcp-retries-max-attempts 5 ``` ### Using Configuration File Modify `prowler/providers/gcp/config.py`: ```python theme={null} DEFAULT_RETRY_ATTEMPTS = 5 # Default: 3 ``` ## How It Works * **Automatic Detection**: Handles HTTP 429 and quota exceeded errors * **Exponential Backoff**: Each retry uses randomized exponential backoff * **Centralized Config**: All GCP services use the same retry configuration * **Transparent**: No additional code needed in services ## Error Examples Handled ``` HttpError 429 when requesting https://cloudresourcemanager.googleapis.com/v1/projects/vms-uat-eiger:getIamPolicy?alt=json returned "Quota exceeded for quota metric 'Read requests' and limit 'Read requests per minute'" ``` ## Implementation ### Client-Level Configuration ```python theme={null} from prowler.providers.gcp.config import DEFAULT_RETRY_ATTEMPTS client = discovery.build( service, version, credentials=credentials, num_retries=DEFAULT_RETRY_ATTEMPTS ) ``` ### Request-Level Configuration ```python theme={null} response = request.execute(num_retries=DEFAULT_RETRY_ATTEMPTS) ``` ## Services with Retry Support All major GCP services are covered: * Cloud Resource Manager, Compute Engine, IAM * BigQuery, KMS, Cloud Storage, Monitoring * DNS, Logging, Cloud SQL, GKE, API Keys, DataProc ## Validation ### Debug Logging ```bash theme={null} prowler gcp --log-level DEBUG --log-file debuglogs.txt --project-id your-project-id ``` ### Check for Retry Messages ```bash theme={null} grep -i "sleeping\|retry\|quota exceeded" debuglogs.txt ``` ### Expected Output ``` "Sleeping 1.52 seconds before retry 1 of 3" "Sleeping 3.23 seconds before retry 2 of 3" ``` ## Testing in Real Environment 1. **Reduce API Quotas** in GCP Console: * APIs & Services > Quotas * Reduce "Read requests per minute" for Compute Engine API * Reduce "Policy Read Requests per minute" for IAM API 2. **Run Prowler** with debug logging 3. **Monitor logs** for retry messages ## Troubleshooting If experiencing rate limiting: 1. Use `--gcp-retries-max-attempts` flag to increase attempts 2. Request quota increases from Google Cloud support 3. Optimize scanning to reduce simultaneous API calls 4. Verify retry functionality with debug logging ## Official References * [Google Cloud Python Client Libraries](https://cloud.google.com/python/docs) * [Google Cloud Quotas](https://cloud.google.com/docs/quotas) * [Google API Core Retry](https://googleapis.dev/python/google-api-core/latest/retry.html) # GitHub Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/github/authentication Prowler for GitHub offers multiple authentication types across Prowler Cloud and Prowler CLI. ## Common Setup ### Authentication Methods Overview Prowler offers three authentication methods. Fine-Grained Personal Access Tokens are recommended for most use cases. | Method | Best For | Key Benefit | | - | - | - | | [**Fine-Grained Personal Access Token**](#fine-grained-personal-access-token-recommended-for-individual-use) | Individual users, quick setup | Simple, user-scoped access | | [**GitHub App**](#github-app-credentials) | Organizations, automation, CI/CD | Organization-scoped, no personal account dependency | | [**OAuth App Token**](#oauth-app-token) | Delegated user authorization | User-consented access flows | > [!NOTE] > > **Which should I choose?** > > * **Personal scanning or quick setup**: Use Fine-Grained PAT > * **Organization-wide scanning or CI/CD pipelines**: Use GitHub App (recommended for production) > * **Building apps with user authorization**: Use OAuth App > [!WARNING] > > **Classic Personal Access Tokens** > > GitHub has deprecated classic Personal Access Tokens. Use Fine-Grained Tokens instead - they provide granular permission control and better security. ### Required Permissions Required permissions depend on the scan scope: user repositories, organization repositories, or both. #### Repository Permissions Required for scanning repository security settings: | Permission | Access Level | Purpose | Checks Enabled | | - | - | - | - | | **Administration** | Read | Branch protection, security and Actions settings | All branch protection checks, secret scanning status, `repository_default_workflow_permissions_read_only` | | **Contents** | Read | File existence checks | `repository_public_has_securitymd_file`, `repository_has_codeowners_file` | | **Metadata** | Read | Basic repository information | All checks (automatically granted) | | **Dependabot alerts** | Read | Dependency vulnerability scanning | `repository_dependency_scanning_enabled` | > [!NOTE] > > **Pull requests permission is optional.** It's only needed if you want to audit PR-specific settings beyond what branch protection provides. #### Organization Permissions Required for scanning organization-level security settings: > [!NOTE] > > **For Fine-Grained PATs:** Organization permissions only appear when the **Resource Owner** is set to an organization (not your personal account). > > **For GitHub Apps:** Organization permissions are configured during app creation and apply to all organizations where the app is installed. | Permission | Access Level | Purpose | Checks Enabled | | - | - | - | - | | **Administration** | Read | Organization security policies and Actions settings | `organization_members_mfa_required`, `organization_repository_creation_limited`, `organization_default_repository_permission_strict`, `organization_default_workflow_permissions_read_only`, `organization_actions_pull_request_approval_disabled` | | **Members** | Read | Member access reviews | Organization membership auditing | #### Account Permissions (Fine-Grained PAT only) | Permission | Access Level | Purpose | | - | - | - | | **Email addresses** | Read | User email verification | > [!NOTE] > > GitHub Apps don't have account-level permissions - they operate at the organization/repository level. ### Permissions and Check Coverage With the **Read-only permissions** listed above, Prowler can run: | Check Category | Coverage | Notes | | - | - | - | | Branch protection checks (12 checks) | ✅ Full | Signed commits, status checks, PR reviews, etc. | | Repository security checks | ✅ Full | Secret scanning, Dependabot, SECURITY.md, CODEOWNERS, default workflow permissions | | Organization checks (5 checks) | ✅ Full | MFA, repo creation policies, default permissions, Actions workflow permissions | | Compliance frameworks | ✅ Full | CIS GitHub Benchmark and others | | Merge settings (`delete_branch_on_merge`) | ⚠️ MANUAL | Requires write permission (see below) | **Check that returns `MANUAL` status with Read-only permissions:** * `repository_branch_delete_on_merge_enabled` > [!WARNING] > > **About Write Permissions** > > The `delete_branch_on_merge` setting is only returned by the GitHub API when the token has **Administration: Read and write** permission. > > **Granting Write permissions is not recommended under any circumstances:** > > * Token can modify repository settings > * Token can change branch protection rules > * Violates the principle of least privilege > > **Recommendation:** Accept `MANUAL` status for this single check rather than granting write access. This limitation applies equally to Fine-Grained PATs and GitHub Apps. ### Step-by-Step Permission Assignment #### Fine-Grained Personal Access Token (Recommended for Individual Use) **Benefits of Fine-Grained Tokens** Fine-Grained Personal Access Tokens are ideal for: * **Individual users** scanning their own repositories * **Quick setup** without app registration overhead * **Temporary access** with mandatory expiration * **Repository-specific access** when you only need to scan certain repos **Create a Fine-Grained Token:** > [!TIP] > > **Quick Setup:** Use these pre-configured links to create a token with the required permissions already selected: > > * [Create token for user repositories](https://github.com/settings/personal-access-tokens/new?name=Prowler+Security+Scanner\&description=Fine-grained+PAT+for+Prowler+security+scanning\&expires_in=90\&administration=read\&contents=read\&vulnerability_alerts=read\&emails=read) — scans personal repositories > * [Create token for organization scanning](https://github.com/settings/personal-access-tokens/new?name=Prowler+Security+Scanner\&description=Fine-grained+PAT+for+Prowler+organization+security+scanning\&expires_in=90\&administration=read\&contents=read\&vulnerability_alerts=read\&emails=read\&organization_administration=read\&members=read) — scans organization repositories and settings > > For organization scanning, change the **Resource Owner** to the target organization after the page loads. Organization permissions only appear when an organization is selected. 1. Navigate to **GitHub Settings** > **Developer settings**. 2. Click **Personal access tokens** > **Fine-grained tokens** > **Generate new token**. 3. Configure basic settings: * **Token name**: Descriptive name (e.g., "Prowler Security Scanner") * **Expiration**: 90 days or less (recommended) * **Resource owner**: * Personal account (for user repositories) * Organization name (for organization scanning - requires admin approval) * **Repository access**: "All repositories" (recommended) 4. Configure **Repository permissions**: * Administration: Read * Contents: Read * Metadata: Read (auto-selected) * Dependabot alerts: Read 5. Configure **Organization permissions** (only appears when Resource owner is an organization): * Administration: Read * Members: Read 6. Configure **Account permissions**: * Email addresses: Read (optional) 7. Click **Generate token** and copy the token immediately. > [!WARNING] > > GitHub shows the token only once. Store it securely. ![GitHub Fine-Grained Token Permissions](https://mintcdn.com/prowler/3MeTQEK7UW2A9QiV/images/providers/github-pat-permissions.png?fit=max\&auto=format\&n=3MeTQEK7UW2A9QiV\&q=85\&s=e654ca94242146c785dee31b834bd19f) #### OAuth App Token **Recommended OAuth App Use Cases:** Use OAuth App Tokens when building applications that need delegated user permissions and explicit user authorization. **OAuth Scopes:** * `repo`: Full control of repositories * `read:org`: Read organization and team membership * `admin:org`: Required by `organization_default_workflow_permissions_read_only` and `organization_actions_pull_request_approval_disabled` to read the organization Actions workflow permissions * `read:user`: Read user profile data **Create an OAuth App:** 1. Navigate to **GitHub Settings** > **Developer settings** > **OAuth Apps**. 2. Click **New OAuth App** and complete: * Application name * Homepage URL * Authorization callback URL 3. Obtain authorization code: ``` https://github.com/login/oauth/authorize?client_id={app_id} ``` 4. Exchange authorization code for access token: ``` https://github.com/login/oauth/access_token?code={code}&client_id={app_id}&client_secret={secret} ``` #### GitHub App Credentials > [!NOTE] > > **When to Use GitHub Apps** > > GitHub Apps are ideal for: > > * **Organization-wide scanning** without tying access to a personal account > * **CI/CD pipelines** where you need machine identity (not user-based) > * **Multi-organization setups** with centralized app management > * **Audit compliance** where you need to track app-level access separately from users > > GitHub Apps use the same permission model as Fine-Grained PATs - both provide full access to all Prowler checks. **GitHub App Permissions:** If a GitHub App is required: **Repository permissions:** | Permission | Access Level | Purpose | Checks Enabled | | - | - | - | - | | **Administration** | Read | Branch protection, security and Actions settings | All branch protection checks, `repository_secret_scanning_enabled`, `repository_default_workflow_permissions_read_only` | | **Contents** | Read | File existence checks | `repository_public_has_securitymd_file`, `repository_has_codeowners_file` | | **Metadata** | Read | Basic repository information | All checks (automatically granted) | | **Dependabot alerts** | Read | Dependency vulnerability scanning | `repository_dependency_scanning_enabled` | **Organization permissions:** | Permission | Access Level | Purpose | Checks Enabled | | - | - | - | - | | **Administration** | Read | Organization security policies and Actions settings | `organization_members_mfa_required`, `organization_repository_creation_limited`, `organization_default_repository_permission_strict`, `organization_default_workflow_permissions_read_only`, `organization_actions_pull_request_approval_disabled` | | **Members** | Read | Member access reviews | Organization membership auditing | **Create a GitHub App:** 1. Navigate to **GitHub Settings** > **Developer settings** > **GitHub Apps**. 2. Click **New GitHub App** and complete: * **GitHub App name**: Descriptive name (e.g., "Prowler Security Scanner") * **Homepage URL**: Your organization's URL or Prowler documentation * **Webhook**: Uncheck "Active" (Prowler doesn't need webhooks) 3. Configure **Repository permissions** (see table above): * Administration: Read * Contents: Read * Metadata: Read (auto-selected) * Dependabot alerts: Read 4. Configure **Organization permissions** (see table above): * Administration: Read * Members: Read 5. Under **Where can this GitHub App be installed?**, select: * "Only on this account" for single-organization use * "Any account" if you need to install across multiple organizations 6. Click **Create GitHub App**. 7. On the app settings page: * Record the **App ID** (displayed at the top) * Click **Generate a private key** and download the `.pem` file 8. Install the GitHub App: * Click **Install App** in the left sidebar * Select target account/organization * Choose "All repositories" or select specific repositories * Click **Install** > [!WARNING] > > **Private Key Security** > > Store the `.pem` private key securely. Anyone with this key can authenticate as your GitHub App. Never commit it to version control. *** ## Prowler Cloud Authentication For step-by-step setup instructions for Prowler Cloud, see the [Getting Started Guide](/user-guide/providers/github/getting-started-github#prowler-cloud). ### Using Personal Access Token 1. In Prowler Cloud, navigate to **Configuration** > **Providers** > **Add Provider** > **GitHub**. 2. Enter your GitHub Account ID (username or organization name). 3. Select **Personal Access Token** as the authentication method. 4. Enter your Fine-Grained Personal Access Token. 5. Click **Verify** to test the connection, then **Save**. ### Using OAuth App Token 1. Follow the same steps as Personal Access Token. 2. Select **OAuth App Token** as the authentication method. 3. Enter your OAuth App Token. ### Using GitHub App 1. Follow the same steps as Personal Access Token. 2. Select **GitHub App** as the authentication method. 3. Enter your GitHub App ID and upload the private key (`.pem` file). For complete step-by-step instructions, see the [Getting Started Guide](/user-guide/providers/github/getting-started-github#prowler-cloud). *** ## Prowler CLI Authentication ### Authentication Methods Prowler CLI automatically detects credentials using environment variables in this order: 1. `GITHUB_PERSONAL_ACCESS_TOKEN` 2. `GITHUB_OAUTH_APP_TOKEN` 3. `GITHUB_APP_ID` and `GITHUB_APP_KEY` ### Using Environment Variables (Recommended) ```bash theme={null} # Personal Access Token (Recommended) export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxx" prowler github # OAuth App Token export GITHUB_OAUTH_APP_TOKEN="oauth_token_here" prowler github # GitHub App export GITHUB_APP_ID="123456" export GITHUB_APP_KEY="$(cat /path/to/private-key.pem)" prowler github ``` ### Using CLI Flags ```bash theme={null} # Personal Access Token prowler github --personal-access-token ghp_xxxxxxxxxxxx # OAuth App Token prowler github --oauth-app-token oauth_token_here # GitHub App prowler github --github-app-id 123456 --github-app-key-path /path/to/private-key.pem ``` ### Scan Scope > [!WARNING] > > **Understanding Scan Scope** > > What Prowler scans depends on the invocation method: > > | Command | What Gets Scanned | Organization Checks? | > | - | - | - | > | `prowler github` | All accessible repositories | No | > | `prowler github --repository owner/repo` | Single repository | No | > | `prowler github --organization org-name` | Organization repos + settings | Yes | > > **Key Point:** Scanning user repositories does NOT include organization-level checks. To audit organization MFA, security policies, etc., you must use `--organization`. **Scan user repositories:** ```bash theme={null} prowler github prowler github --repository username/my-repo ``` **Scan organizations:** ```bash theme={null} prowler github --organization org-name prowler github --organization org1 --organization org2 ``` **Filter scans:** ```bash theme={null} prowler github --severity critical prowler github --checks repository_default_branch_protection_enabled prowler github --compliance cis_1.0_github ``` For complete step-by-step instructions, see the [Getting Started Guide](/user-guide/providers/github/getting-started-github#prowler-cli). *** ## Troubleshooting ### "Insufficient Permissions" Errors **Symptom:** Checks fail or return `MANUAL` status. **Solutions:** 1. Verify token has all required permissions 2. For organization scans, ensure organization approved the Fine-Grained Token 3. For merge settings checks, accept `MANUAL` status (Write permission not recommended) ### "No Organizations Found" **Symptom:** Prowler doesn't find organizations even though you're a member. **Cause:** Fine-Grained Token's Resource Owner is set to personal account. **Solution:** Create a new token with Resource Owner set to the organization and get it approved by an admin. ### Organization Checks Return `MANUAL` **Symptom:** Checks like `organization_members_mfa_required` return `MANUAL`. **Cause:** Token lacks `Organization → Administration: Read` permission. **Solutions:** 1. Edit token and grant `Organization → Administration: Read` 2. Ensure token's **Resource owner** is the organization (not personal account) 3. Get organization admin approval ### Token Not Showing Organization Permissions **Symptom:** Can't find Organization permissions section when creating token. **Cause:** **Resource owner** is set to personal account. **Solution:** Change **Resource owner** dropdown to the organization name. Organization permissions section will appear. ### Rate Limiting **Symptom:** "API rate limit exceeded" errors. **Solutions:** * Scan during off-peak hours * Use `--repository` to scan specific repos instead of all * Implement delays between scans ### Token Expired or Revoked **Symptom:** Authentication fails with valid-looking token. **Solutions:** 1. Check token expiration date in GitHub settings 2. Verify token wasn't revoked 3. For Fine-Grained Tokens, check if organization approval was revoked 4. Generate a new token *** ## Additional Resources * [GitHub REST API Authentication](https://docs.github.com/en/rest/authentication) * [Fine-Grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) * [GitHub Apps Documentation](https://docs.github.com/en/apps) * [GitHub API Rate Limits](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api) * [Getting Started Guide](/user-guide/providers/github/getting-started-github) # Getting Started with GitHub Source: https://docs.prowler.com/user-guide/providers/github/getting-started-github This guide covers setting up GitHub security scanning with Prowler. Choose a preferred interface below: > [!NOTE] > > **Understanding GitHub Scan Scope** > > Prowler can scan either: > > * **User Repositories**: All repositories owned by or accessible to a specific GitHub user > * **Organizations**: Repositories and organization-level settings > > **Important**: Scanning user repositories does NOT include organization-level checks (MFA requirements, security policies, etc.). To scan organizations, you must explicitly configure them. > [card] [Prowler Cloud](#prowler-cloud) > > Web-based interface with centralized management > [card] [Prowler CLI](#prowler-cli) > > Command-line interface for local or automated scans *** ## Prowler Cloud > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). [Prowler Cloud Onboarding Github](https://www.youtube-nocookie.com/embed/9ETI84Xpu2g) > Walkthrough video onboarding a GitHub Account using GitHub App. ### Prerequisites Before adding GitHub to Prowler Cloud, ensure you have: 1. **GitHub Account Access** * Personal GitHub account, OR * Admin access to a GitHub organization 2. **Authentication Credentials** * Choose one method (see [Authentication Guide](/user-guide/providers/github/authentication)): * **Fine-Grained Personal Access Token** (Recommended) * OAuth App Token * GitHub App Credentials (Not Recommended - limited data access) ### Step 1: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Go to **Configuration** → **Providers** ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click **Add Provider** ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select **GitHub** ![Select GitHub](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-github.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=c49e914dd3c14aea7ae4af8fadbe6d61) ### Step 2: Configure GitHub Account 5. Add the **GitHub Account ID** and an optional alias: * **Account ID**: Your GitHub username (e.g., `username`) or organization name (e.g., `org-name`) * **Alias** (optional): Friendly name for this connection (e.g., `My Personal Repos` or `Prowler Org`) ![Add GitHub Account ID](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-github-account-id.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=a3da8688185a1932da6c9e915ddacdeb) 6. Click **Next** ### Step 3: Choose Authentication Method > [!NOTE] > > **Recommended: Fine-Grained Personal Access Token** > > **Fine-Grained Personal Access Tokens** are strongly recommended because they provide: > > * Best data access for comprehensive security scanning > * Granular permission control > * Resource-specific access > > **GitHub Apps are not recommended** — they provide the most limited access to GitHub data for security scanning purposes. 7. Select your preferred authentication method: ![Select auth method](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-auth-method.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=e65a117f6a339e997f41b31f6a27ea64) > [tab] Personal Access Token (Recommended) > > ![Configure Personal Access Token](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/auth-pat.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=4ad5c092fea37d4fe866607a9f0e024d) > > **Recommended method** - provides the best data access for security scanning. > > 1. Enter your Fine-Grained Personal Access Token > 2. Click **Verify** to test the connection > 3. Click **Save** > > **Don't have a token yet?** [Create a pre-configured token on GitHub](https://github.com/settings/personal-access-tokens/new?name=Prowler+Security+Scanner\&description=Fine-grained+PAT+for+Prowler+security+scanning\&expires_in=90\&administration=read\&contents=read\&vulnerability_alerts=read\&emails=read) or see [How to create a Personal Access Token](/user-guide/providers/github/authentication#create-a-fine-grained-personal-access-token) for detailed instructions. > [tab] OAuth App Token > > ![Configure OAuth App Token](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/auth-oauth.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=dce7e57b99722e577e684eebcc326c0a) > > For applications requiring user consent and delegated permissions. > > 1. Enter your OAuth App Token > 2. Click **Verify** to test the connection > 3. Click **Save** > > **Don't have an OAuth token?** See [How to create an OAuth App Token](/user-guide/providers/github/authentication#oauth-app-token) > [tab] GitHub App (Not Recommended) > > ![Configure GitHub App](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/auth-github-app.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=e124221eff1709a0cc3e38b6a5b3a53b) > > > [!WARNING] > > > > **Not recommended** - most limited data access. Use only if required by organization policy. > > 1. Enter your GitHub App ID > 2. Upload or paste your Private Key (`.pem` file) > 3. Click **Verify** to test the connection > 4. Click **Save** > > **Don't have a GitHub App?** See [How to create a GitHub App](/user-guide/providers/github/authentication#github-app-credentials) 8. Click **Start Scan** to begin your first security assessment ### Step 5: View Results Once the scan completes, you can: * View security findings in the dashboard * Export results in multiple formats (JSON, CSV, HTML) * Set up continuous scanning schedules * Configure alerts for critical findings *** ## Prowler CLI ### Prerequisites Before running Prowler CLI for GitHub, ensure you have: 1. **Prowler Installed** ```bash theme={null} # Install via pip pip install prowler # Or via uv (from the cloned repo) uv sync ``` 2. **Authentication Credentials** * Choose one method (see [Authentication Guide](/user-guide/providers/github/authentication)): * **Fine-Grained Personal Access Token** (Recommended) * OAuth App Token * GitHub App Credentials (Not Recommended) ### Authentication Setup Prowler CLI automatically detects authentication credentials using environment variables in this order: 1. `GITHUB_PERSONAL_ACCESS_TOKEN` 2. `GITHUB_OAUTH_APP_TOKEN` 3. `GITHUB_APP_ID` and `GITHUB_APP_KEY` > [tab] Environment Variables (Recommended) > > ```bash theme={null} > # Personal Access Token (Recommended) > export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxx" > > # OAuth App Token > export GITHUB_OAUTH_APP_TOKEN="oauth_token_here" > > # GitHub App > export GITHUB_APP_ID="123456" > export GITHUB_APP_KEY="$(cat /path/to/private-key.pem)" > ``` > > Then run Prowler without additional flags: > > ```bash theme={null} > prowler github > ``` > [tab] CLI Flags > > ```bash theme={null} > # Personal Access Token > prowler github --personal-access-token ghp_xxxxxxxxxxxx > > # OAuth App Token > prowler github --oauth-app-token oauth_token_here > > # GitHub App > prowler github --github-app-id 123456 --github-app-key-path /path/to/private-key.pem > ``` **Don't have credentials yet?** See the [Authentication Guide](/user-guide/providers/github/authentication) for step-by-step instructions. ### Scan Scope: Understanding What Gets Scanned > [!WARNING] > > **Distinguishing User Scans from Organization Scans** > > The scan scope depends entirely on the Prowler CLI invocation method: > > | Command | What Gets Scanned | Organization Checks Included? | > | - | - | - | > | `prowler github` | All repositories the token has access to | No | > | `prowler github --repository owner/repo` | Single specified repository | No | > | `prowler github --organization org-name` | Organization repos + org settings | Yes | > | `prowler github --organization org-name --repository owner/repo` | Organization + single repository | Yes | > > **Key Points:** > > * Scanning **user repositories** does NOT run organization-level checks > * To audit organization MFA, security policies, etc., the `--organization` flag is required > * Members of multiple organizations should specify each one explicitly ### Scanning User Repositories Scan repositories owned by your user account: ```bash theme={null} # Scan all repositories accessible to your token prowler github # Scan a specific repository prowler github --repository username/my-repo # Scan multiple specific repositories prowler github --repository username/repo1 --repository username/repo2 ``` **What gets scanned:** * Repository security settings * Branch protection rules * Secret scanning configuration * Dependabot settings * Organization-level policies (not included) ### Scanning Organizations Scan organization repositories and organization-level security settings: ```bash theme={null} # Scan a single organization prowler github --organization prowler-cloud # Scan multiple organizations prowler github --organization org1 --organization org2 # Scan organization and specific repositories within it prowler github --organization my-org --repository my-org/critical-repo ``` **What gets scanned:** * All organization repositories * Repository security settings * Organization MFA requirements * Organization security policies * Member access and permissions ### Scan Scoping Scan scoping controls which repositories and organizations Prowler includes in a security assessment. By default, Prowler scans all repositories accessible to the authenticated user or organization. To limit the scan to specific repositories or organizations, use the following flags. #### Scanning Specific Repositories To restrict the scan to one or more repositories, use the `--repository` flag followed by the repository name(s) in `owner/repo-name` format: ```console theme={null} prowler github --repository owner/repo-name ``` To scan multiple repositories, specify them as space-separated arguments: ```console theme={null} prowler github --repository owner/repo-name-1 owner/repo-name-2 ``` #### Scanning Specific Organizations To restrict the scan to one or more organizations or user accounts, use the `--organization` flag: ```console theme={null} prowler github --organization my-organization ``` To scan multiple organizations, specify them as space-separated arguments: ```console theme={null} prowler github --organization org-1 org-2 ``` #### Scanning Specific Repositories Within an Organization To scan specific repositories within an organization, combine the `--organization` and `--repository` flags. The `--organization` flag qualifies unqualified repository names automatically: ```console theme={null} prowler github --organization my-organization --repository my-repo ``` This scans only `my-organization/my-repo`. Fully qualified repository names (`owner/repo-name`) are also supported alongside `--organization`: ```console theme={null} prowler github --organization my-org --repository my-repo other-owner/other-repo ``` In this case, `my-repo` is qualified as `my-org/my-repo`, while `other-owner/other-repo` is used as-is. > [!NOTE] > > The `--repository` and `--organization` flags can be combined with any authentication method. ### Filtering Scans Customize your scan scope with these options: ```bash theme={null} # Run only critical severity checks prowler github --severity critical # Run specific checks prowler github --checks repository_default_branch_protection_enabled,organization_members_mfa_required # Exclude specific checks prowler github --excluded-checks repository_archived # Scan with specific compliance framework prowler github --compliance cis_1.0_github # Output results in specific format prowler github --output-formats json,csv,html ``` ### Example Workflows > [tab] Quick Security Assessment > > ```bash theme={null} > # Scan your personal repositories for critical issues > export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx" > prowler github --severity critical high > ``` > [tab] Organization Compliance Audit > > ```bash theme={null} > # Full organization scan with CIS compliance > export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx" > prowler github \ > --organization prowler-cloud \ > --compliance cis_1.0_github \ > --output-formats json,html > ``` > [tab] CI/CD Integration > > ```bash theme={null} > # Scan specific repository in CI pipeline > prowler github \ > --personal-access-token "$GITHUB_TOKEN" \ > --repository "$GITHUB_REPOSITORY" \ > --severity critical \ > --output-formats json > > # Exit with non-zero if critical findings > if grep -q '"Status": "FAIL".*"Severity": "critical"' prowler-output*.json; then > echo "Critical security issues found!" > exit 1 > fi > ``` > [tab] Multi-Organization Scan > > ```bash theme={null} > # Scan multiple organizations you're part of > export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx" > prowler github \ > --organization org1 \ > --organization org2 \ > --organization org3 \ > --output-formats csv > ``` ### Viewing Prowler CLI Scan Results Prowler CLI generates results in multiple formats: ```bash theme={null} # Results are saved in ./output/ directory by default ls output/ # View HTML report in browser open output/prowler-output-*.html # Parse JSON results with jq cat output/prowler-output-*.json | jq '.findings[] | select(.Status=="FAIL")' # Import CSV into spreadsheet open output/prowler-output-*.csv ``` *** ## Next Steps > [card] [Authentication Guide](/user-guide/providers/github/authentication) > > Detailed permissions and token creation > [card] [Available Checks](https://hub.prowler.com/github) > > Browse all GitHub security checks > [card] [Compliance Frameworks](https://hub.prowler.com/compliance) > > CIS, NIST, and other frameworks > [card] [Troubleshooting](/user-guide/providers/github/authentication#troubleshooting) > > Common issues and solutions ## Additional Resources * [GitHub REST API Documentation](https://docs.github.com/en/rest) * [Fine-Grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) * [GitHub Security Best Practices](https://docs.github.com/en/code-security) * [Prowler CLI Reference](/getting-started/basic-usage/prowler-cli) # Google Workspace Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/googleworkspace/authentication [Added in:  5.19.0](https://github.com/prowler-cloud/prowler/releases/tag/5.19.0) Prowler for Google Workspace uses a **Service Account with Domain-Wide Delegation** to authenticate to the Google Workspace Admin SDK and the Cloud Identity Policy API. This allows Prowler to read directory data and domain-level application policies on behalf of a super administrator without requiring an interactive login. ## Required Open Authorization (OAuth) Scopes Prowler requests the following read-only OAuth 2.0 scopes: | Scope | Description | | - | - | | `https://www.googleapis.com/auth/admin.directory.user.readonly` | Read access to user accounts and their admin status | | `https://www.googleapis.com/auth/admin.directory.domain.readonly` | Read access to domain information | | `https://www.googleapis.com/auth/admin.directory.customer.readonly` | Read access to customer information (Customer ID) | | `https://www.googleapis.com/auth/admin.directory.orgunit.readonly` | Read access to organizational unit hierarchy (identifies the root OU for policy filtering) | | `https://www.googleapis.com/auth/cloud-identity.policies.readonly` | Read access to domain-level application policies (required for Calendar, Chat, Drive, Gmail, Groups, Marketplace, Security, and Sites service checks) | | `https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly` | Read access to admin roles and role assignments | > [!WARNING] > > The delegated user must be a **super administrator** in your Google Workspace organization. Using a non-admin account will result in permission errors when accessing the Admin SDK. ### Optional Scope for Edition Context Prowler can read which Google Workspace editions the tenant holds, Cloud Identity Premium included, and state in a finding when the audited feature is not sold on them (for example, Data Loss Prevention (DLP) for Drive or Google session control). This needs the Enterprise License Manager API enabled in the GCP project (Step 2) and the scope `https://www.googleapis.com/auth/apps.licensing` added to the Domain-Wide Delegation list (Step 5). Without the scope, every check runs the same and findings carry no edition context. > [!WARNING] > > The `apps.licensing` scope is Google's "view and manage licenses" scope and has no read-only variant. Prowler only lists license assignments, but anyone holding the Service Account key could assign or revoke licenses with it on behalf of the super administrator. Grant it only if you want the edition context, and protect the key accordingly. ## Setup Steps ### Step 1: Create a Google Cloud Platform (GCP) Project (if Needed) If no GCP project exists, create one at [https://console.cloud.google.com](https://console.cloud.google.com). The project is only used to host the Service Account — it does not need to have any Google Workspace data in it. ### Step 2: Enable Required APIs In the [Google Cloud Console](https://console.cloud.google.com), select the target project and enable each of the following APIs: | API | Service Name | Required For | | - | - | - | | **[Admin SDK API](https://console.cloud.google.com/apis/library/admin.googleapis.com)** | `admin.googleapis.com` | Directory service checks (users, roles, domains) | | **[Cloud Identity API](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com)** | `cloudidentity.googleapis.com` | All service checks except Directory (domain-level application policies) | | **[Enterprise License Manager API](https://console.cloud.google.com/apis/library/licensing.googleapis.com)** | `licensing.googleapis.com` | Optional: edition context in findings (see Optional Scope for Edition Context) | For each API: 1. Open the link above, or navigate to **APIs & Services → Library** and search for the API name 2. Confirm the target project is selected in the project picker 3. Click **Enable** > [!NOTE] > > The Admin SDK API and the Cloud Identity API must be enabled in the same GCP project that hosts the Service Account. All service checks except Directory will return no findings if the Cloud Identity API is not enabled. The Identity and Access Management (IAM) API (`iam.googleapis.com`) is a different API: enabling it does not replace the Cloud Identity API. ### Step 3: Create a Service Account 1. In the Google Cloud Console, navigate to **IAM & Admin → Service Accounts** 2. Click **Create Service Account** 3. Give it a descriptive name (e.g., `prowler-googleworkspace-reader`) 4. Click **Create and Continue** 5. Skip the optional role and user access steps — click **Done** > [!NOTE] > > The Service Account does not need any GCP IAM roles. Its access to Google Workspace is granted entirely through Domain-Wide Delegation in the next steps. ### Step 4: Generate a JSON Key 1. Click the newly created Service Account 2. Navigate to the **Keys** tab 3. Click **Add Key → Create new key** 4. Select **JSON** format 5. Click **Create** — the key file will download automatically 6. Store it securely (e.g., `~/.config/prowler/googleworkspace-sa.json`) > [!WARNING] > > This JSON key grants access to your Google Workspace organization. Never commit it to version control, share it in plain text, or store it in an insecure location. #### Service Account Key Creation Is Disabled Organizations created on or after May 3, 2024 enforce the [Secure by Default](https://docs.cloud.google.com/resource-manager/docs/secure-by-default-organizations) organization policy `iam.managed.disableServiceAccountKeyCreation`, and the **Add key** dialog shows "Service account key creation is disabled". To create the key, a user with the Organization Policy Administrator role (`roles/orgpolicy.policyAdmin`) on the organization must turn off enforcement for the project that hosts the Service Account: 1. In the Google Cloud Console, select the project and navigate to **IAM & Admin → Organization Policies** 2. Open **Disable service account key creation** (`iam.managed.disableServiceAccountKeyCreation`) and click **Manage policy** 3. Select **Override parent's policy**, click **Add a rule**, set **Enforcement** to **Off**, and click **Set policy** 4. Return to the Service Account **Keys** tab and create the key Alternatively, override the policy with the Google Cloud CLI: ```yaml policy.yaml theme={null} name: projects/PROJECT_ID/policies/iam.managed.disableServiceAccountKeyCreation spec: rules: - enforce: false ``` ```console theme={null} gcloud org-policies set-policy policy.yaml ``` The constraint only blocks new key creation. Keys that already exist keep working, so enforcement can be restored once the key has been downloaded. ### Step 5: Configure Domain-Wide Delegation in Google Workspace 1. Navigate to the [Google Workspace Admin Console](https://admin.google.com) 2. Navigate to **Security → Access and data control → API controls** 3. Click **Manage Domain Wide Delegation** 4. Click **Add new** 5. Enter the **Client ID** of the Service Account (found in the JSON key as `client_id`, or on the Service Account details page) 6. In the **OAuth scopes** field, enter the following scopes as a comma-separated list: ``` https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/cloud-identity.policies.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly ``` To enable the optional edition context, append `,https://www.googleapis.com/auth/apps.licensing` to the list. 7. Click **Authorize** > [!NOTE] > > Domain-Wide Delegation must be configured by a Google Workspace **super administrator**. It may take a few minutes to propagate after saving. ### Step 6: Provide Credentials to Prowler * **Prowler Cloud:** Paste the Service Account JSON content and enter the delegated user email in the credentials form when configuring the Google Workspace provider. * **Prowler CLI:** Export the credentials as environment variables: ```console theme={null} export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/googleworkspace-sa.json" export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com" prowler googleworkspace ``` Alternatively, to pass credentials as a string (e.g., in CI/CD pipelines): ```console theme={null} export GOOGLEWORKSPACE_CREDENTIALS_CONTENT=$(cat /path/to/googleworkspace-sa.json) export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com" prowler googleworkspace ``` ## How Prowler Resolves Credentials Prowler resolves credentials in the following order: 1. `GOOGLEWORKSPACE_CREDENTIALS_FILE` environment variable 2. `GOOGLEWORKSPACE_CREDENTIALS_CONTENT` environment variable The delegated user must be provided via the `GOOGLEWORKSPACE_DELEGATED_USER` environment variable. ## Best Practices * **Use environment variables** — Never hardcode credentials in scripts or commands * **Use a dedicated Service Account** — Create one specifically for Prowler, separate from other integrations * **Use read-only scopes** — Prowler only requires the read-only scopes listed above * **Restrict key access** — Set file permissions to `600` on the JSON key file * **Rotate keys regularly** — Delete and regenerate the JSON key periodically * **Use a least-privilege super admin** — Consider using a dedicated super admin account for Prowler's delegated user rather than a personal admin account ```bash theme={null} # Secure the key file chmod 600 /path/to/googleworkspace-sa.json ``` ## Troubleshooting ### `GoogleWorkspaceMissingDelegatedUserError` The delegated user email was not provided. Set it via environment variable: ```bash theme={null} export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com" ``` ### `GoogleWorkspaceNoCredentialsError` No credentials were found. Ensure either `GOOGLEWORKSPACE_CREDENTIALS_FILE` or `GOOGLEWORKSPACE_CREDENTIALS_CONTENT` is set. ### `GoogleWorkspaceInvalidCredentialsError` The JSON key file is malformed or cannot be parsed. Verify the file was downloaded correctly and is valid JSON: ```bash theme={null} python3 -c "import json; json.load(open('/path/to/key.json'))" && echo "Valid JSON" ``` ### `GoogleWorkspaceImpersonationError` The Service Account cannot impersonate the delegated user. This usually means Domain-Wide Delegation has not been configured, or the OAuth scopes are incorrect. Verify: * The Service Account Client ID is correctly entered in the Admin Console * All required OAuth scopes are included * The delegated user is a super administrator ### Permission Denied on Admin SDK Calls If Prowler connects but returns empty results or permission errors for specific API calls: * Confirm Domain-Wide Delegation is fully propagated (wait a few minutes after setup) * Verify all scopes are authorized in the Admin Console * Ensure the delegated user is an active super administrator ### Policy API Checks Return No Findings If the Directory checks run successfully but other service checks (Calendar, Chat, Drive, Gmail, Groups, Marketplace, Security, Sites) return no findings, the Cloud Identity Policy API is not reachable for this Service Account. Verify: * The **Cloud Identity API** is enabled in the GCP project hosting the Service Account (Step 2) * The scope `https://www.googleapis.com/auth/cloud-identity.policies.readonly` is included in the Domain-Wide Delegation OAuth scopes list in the Admin Console (Step 5) * The delegated user is a super administrator (the Policy API only returns data to super admins) * Domain-Wide Delegation has had time to propagate after adding the new scope (a few minutes) # Getting Started With Google Workspace on Prowler Source: https://docs.prowler.com/user-guide/providers/googleworkspace/getting-started-googleworkspace Prowler for Google Workspace audits the organization's Google Workspace environment for security misconfigurations, including super administrator account hygiene, domain settings, and more. ## Prerequisites Set up authentication for Google Workspace with the [Google Workspace Authentication](/user-guide/providers/googleworkspace/authentication) guide before starting either path: * **Service Account:** Create a Service Account in a GCP project with Domain-Wide Delegation enabled. * **OAuth Scopes:** Authorize the required read-only OAuth scopes in the Google Workspace Admin Console. * **Customer ID:** Identify the Google Workspace Customer ID to use as the provider identifier. * **Delegated User:** Have the email of a super administrator to use as the delegated user. > [card] [Prowler Cloud](#prowler-cloud) > > Onboard Google Workspace using Prowler Cloud > [card] [Prowler CLI](#prowler-cli) > > Onboard Google Workspace using Prowler CLI ## Prowler Cloud [Added in:  5.21.0](https://github.com/prowler-cloud/prowler/releases/tag/5.21.0) > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Step 1: Locate the Customer ID 1. Log into the [Google Workspace Admin Console](https://admin.google.com). 2. Navigate to "Account" > "Account Settings". 3. Find the **Customer ID** on the Account Settings page. ![Google Workspace Customer ID](https://mintcdn.com/prowler/JS11-QKE8N3jq-1e/images/providers/googleworkspace-customer-id.png?fit=max\&auto=format\&n=JS11-QKE8N3jq-1e\&q=85\&s=acf6906d2027ee8bf22292d144dadf27) > [!NOTE] > > The Customer ID starts with the letter "C" followed by alphanumeric characters (e.g., `C0xxxxxxx`). This value acts as the unique identifier for the Google Workspace account in Prowler Cloud. ### Step 2: Open Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up). 2. Navigate to "Configuration" > "Providers". ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider". ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Google Workspace". ![Select Google Workspace](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-googleworkspace-prowler-cloud.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=d41aa287f78c6128a601d67d5a40b313) ### Step 3: Provide Credentials 1. Enter the **Customer ID** and an optional alias, then click "Next". ![Google Workspace Customer ID Form](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/googleworkspace-customer-id-form.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=afc65f02385fd2f1a2d5ee13e6dfd0f2) 2. Paste the **Service Account JSON** credentials content. 3. Enter the "Delegated User Email" (a super administrator in the Google Workspace organization). ![Google Workspace Credentials Form](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/googleworkspace-credentials-form.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=4a738654333813cc3c65e3c1dfc3e8fd) > [!NOTE] > > The Service Account JSON is the full content of the key file downloaded when creating the Service Account. Paste the entire JSON object, not just the file path. For setup instructions, see the [Authentication guide](/user-guide/providers/googleworkspace/authentication). ### Step 4: Check Connection 1. Click "Check Connection" to verify that the credentials and Domain-Wide Delegation are configured correctly. 2. Prowler will test the Service Account impersonation and Admin SDK access. ![Check Connection](https://mintcdn.com/prowler/saTLkZ1BmMa35TKH/images/providers/googleworkspace-check-connection.png?fit=max\&auto=format\&n=saTLkZ1BmMa35TKH\&q=85\&s=8ba4f622bdc0168dbd37d4664d153b98) > [!NOTE] > > If the connection test fails, verify that Domain-Wide Delegation is properly configured and that all required OAuth scopes are authorized. It may take a few minutes for delegation changes to propagate. See the [Troubleshooting](/user-guide/providers/googleworkspace/authentication#troubleshooting) section for common errors. ### Step 5: Launch the Scan 1. Review the summary. 2. Click "Launch Scan" to start auditing Google Workspace. ![Launch Scan](https://mintcdn.com/prowler/saTLkZ1BmMa35TKH/images/providers/googleworkspace-launch-scan.png?fit=max\&auto=format\&n=saTLkZ1BmMa35TKH\&q=85\&s=70017f33676ddc86d4a21b78e4edf0f4) *** ## Prowler CLI [Added in:  5.19.0](https://github.com/prowler-cloud/prowler/releases/tag/5.19.0) ### Step 1: Set Up Authentication Set your Service Account credentials and delegated user email following the [Google Workspace Authentication](/user-guide/providers/googleworkspace/authentication) guide: ```console theme={null} export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/service-account-key.json" export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com" ``` Alternatively, pass the credentials content directly as a JSON string: ```console theme={null} export GOOGLEWORKSPACE_CREDENTIALS_CONTENT='{"type": "service_account", ...}' export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com" ``` ### Step 2: Run the First Scan Run a baseline scan after credentials are configured: ```console theme={null} prowler googleworkspace ``` Prowler authenticates as the delegated user and runs all available security checks against the Google Workspace organization. ### Step 3: Use a Custom Configuration (Optional) Prowler uses a configuration file to customize provider behavior. To use a custom configuration: ```console theme={null} prowler googleworkspace --config-file /path/to/config.yaml ``` *** # Huawei Cloud Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/huaweicloud/authentication [Added in:  5.37.0](https://github.com/prowler-cloud/prowler/releases/tag/5.37.0) Prowler for Huawei Cloud authenticates against the Huawei Cloud APIs using an IAM user's **Access Key ID** and **Secret Access Key** (AK/SK). Credentials are read exclusively from environment variables to avoid exposing secrets in shell history or process listings; there are no credential CLI flags. ## Required Credentials Prowler requires read access to the Huawei Cloud account. The following values are supported: | Credential | Environment Variable | Description | | - | - | - | | Access Key ID | `HUAWEICLOUD_ACCESS_KEY_ID` (or `HW_ACCESS_KEY`) | Permanent access key ID of the IAM user | | Secret Access Key | `HUAWEICLOUD_SECRET_ACCESS_KEY` (or `HW_SECRET_KEY`) | Secret access key paired with the access key ID | | Domain ID | `HUAWEICLOUD_DOMAIN_ID` (or `HW_DOMAIN_ID`) | Optional account (domain) ID | | Security Token | `HUAWEICLOUD_SECURITY_TOKEN` | Optional security token for temporary credentials | | Region | `HUAWEICLOUD_REGION` (or `HW_REGION`) | Default region(s) when `--region` is not passed (e.g. `eu-west-101`) | | Cloud | `HUAWEICLOUD_CLOUD` (or `HW_CLOUD`) | Scan every region of a cloud (`international`, `europe`, or `china`) when no region is set | > [!NOTE] > > The endpoint domain (`.eu` or `.com`) and the per-region project ID are resolved automatically from the region, so neither endpoint nor project configuration is needed. Multi-region scans work out of the box. For the region precedence rules and the full list of supported regions, see [Regions and Clouds](/user-guide/providers/huaweicloud/getting-started-huaweicloud#regions-and-clouds). > [!WARNING] > > Huawei Cloud runs separate clouds: **International** and **China** (`.com` endpoints) and **Huawei Cloud Europe** (`.eu` endpoints). The region (or `--cloud` selector) determines the endpoint, so accounts outside China must select a region they can reach — for example `eu-west-101` for a Huawei Cloud Europe account. A single set of credentials belongs to one cloud, so it cannot authenticate against both `.com` and `.eu`; scan each account with its own credentials. *** ## API Credentials ### Step 1: Create an Access Key (AK/SK) 1. Log in to the [Huawei Cloud console](https://console-intl.huaweicloud.com). 2. Open **My Credentials** from the account menu, then select **Access Keys**. 3. Click **Create Access Key** and complete the identity verification. 4. Download the `credentials.csv` file — it contains the Access Key ID and Secret Access Key. The secret is not shown again. > [!WARNING] > > Use an IAM user with read-only permissions (for example, the built-in `ReadOnly` policy) rather than the account root credentials. ### Step 2: Configure Authentication Export the credentials as environment variables: ```bash theme={null} export HUAWEICLOUD_ACCESS_KEY_ID="your-access-key-id" export HUAWEICLOUD_SECRET_ACCESS_KEY="your-secret-access-key" ``` Then run Prowler: ```bash theme={null} prowler huaweicloud ``` *** ## Assuming an Agency (Cross-Account) To scan a different account, assume an [agency](https://support.huaweicloud.com/intl/en-us/usermanual-iam/iam_06_0002.html) delegated to your account. Set the agency name and the target account, and Prowler exchanges the base credentials for temporary credentials scoped to the agency: ```bash theme={null} export HUAWEICLOUD_ACCESS_KEY_ID="your-access-key-id" export HUAWEICLOUD_SECRET_ACCESS_KEY="your-secret-access-key" export HUAWEICLOUD_AGENCY_NAME="your-agency-name" export HUAWEICLOUD_ASSUME_DOMAIN_ID="target-account-domain-id" # or HUAWEICLOUD_ASSUME_DOMAIN_NAME prowler huaweicloud ``` | Environment Variable | Description | | - | - | | `HUAWEICLOUD_AGENCY_NAME` | Name of the agency to assume in the target account | | `HUAWEICLOUD_ASSUME_DOMAIN_ID` | Domain ID of the target (delegating) account | | `HUAWEICLOUD_ASSUME_DOMAIN_NAME` | Domain name of the target account (alternative to the domain ID) | *** ## Verifying Authentication To confirm that Prowler can reach the account, run a scan against a single region the account can reach: ```bash theme={null} # China account prowler huaweicloud --region cn-north-4 # International account prowler huaweicloud --region ap-southeast-1 # Huawei Cloud Europe account prowler huaweicloud --region eu-west-101 ``` To scan the account's entire cloud instead, use the `--cloud` selector: ```bash theme={null} prowler huaweicloud --cloud europe ``` A successful run reports findings for the discovered resources. A failed run displays an error message indicating the credential or connectivity issue. *** ## CI/CD Integration For automated pipelines, set the credentials as secret environment variables: **GitHub Actions:** ```yaml theme={null} env: HUAWEICLOUD_ACCESS_KEY_ID: ${{ secrets.HUAWEICLOUD_ACCESS_KEY_ID }} HUAWEICLOUD_SECRET_ACCESS_KEY: ${{ secrets.HUAWEICLOUD_SECRET_ACCESS_KEY }} steps: - name: Run Prowler run: prowler huaweicloud ``` **GitLab CI:** ```yaml theme={null} variables: HUAWEICLOUD_ACCESS_KEY_ID: $HUAWEICLOUD_ACCESS_KEY_ID HUAWEICLOUD_SECRET_ACCESS_KEY: $HUAWEICLOUD_SECRET_ACCESS_KEY prowler_scan: script: - prowler huaweicloud ``` # Getting Started With Huawei Cloud on Prowler Source: https://docs.prowler.com/user-guide/providers/huaweicloud/getting-started-huaweicloud [Added in:  5.37.0](https://github.com/prowler-cloud/prowler/releases/tag/5.37.0) Prowler for Huawei Cloud scans your Huawei Cloud account for security misconfigurations across compute, storage, networking, identity, encryption, database, and logging services. > [!NOTE] > > Huawei Cloud support in Prowler is community-maintained. For commercial support or to request additional service coverage, [contact us](https://prowler.com/contact). ## Prerequisites Set up authentication for Huawei Cloud with the [Huawei Cloud Authentication](/user-guide/providers/huaweicloud/authentication) guide before starting: * Create an Access Key ID and Secret Access Key (AK/SK) for an IAM user with read-only permissions. * Prowler reads the credentials exclusively from environment variables, so secrets are never passed on the command line. ## Prowler CLI ### Run Prowler for Huawei Cloud Once authenticated, export the credentials as environment variables and run Prowler for Huawei Cloud. Environment variables keep secrets out of shell history and process listings: ```bash theme={null} export HUAWEICLOUD_ACCESS_KEY_ID="your-access-key-id" export HUAWEICLOUD_SECRET_ACCESS_KEY="your-secret-access-key" prowler huaweicloud ``` ### Run Specific Checks ```bash theme={null} prowler huaweicloud --checks obs_bucket_public_access iam_user_mfa_enabled ``` ### Run a Specific Service ```bash theme={null} prowler huaweicloud --services iam ``` ## Regions and Clouds Huawei Cloud operates as three separate clouds, and every account belongs to exactly one of them: * **International** — served from the `.com` endpoints (for example `myhuaweicloud.com`). * **China** — also served from the `.com` endpoints, on the China regions (`cn-*`). * **Huawei Cloud Europe** — served from the `.eu` endpoints (for example `myhuaweicloud.eu`). The cloud is a property of the region: each region ID maps to exactly one endpoint domain. Prowler selects the correct endpoint automatically from the region, so no endpoint configuration is required. ### Region Selection Precedence Prowler resolves the regions to scan from the first source that is set, in this order: 1. **`--region` flag** (aliases `--filter-region`, `-f`) — one or more explicit region IDs. 2. **`HUAWEICLOUD_REGION`** (or `HW_REGION`) environment variable — one or more region IDs, separated by spaces or commas. 3. **`--cloud` selector** (or `HUAWEICLOUD_CLOUD` / `HW_CLOUD`) — expands to every region of the selected cloud. 4. **Default** — when none is set, Prowler falls back to its built-in region list. A more specific source always wins: `--region` overrides `HUAWEICLOUD_REGION`, which overrides `--cloud`. ### Select Specific Regions To scan a defined set of regions, pass the region IDs to `--region` or set `HUAWEICLOUD_REGION`. Accounts outside China must select a region they can reach — for example `eu-west-101` for Huawei Cloud Europe or `ap-southeast-1` for International. ```bash theme={null} # Flag (one or more regions) prowler huaweicloud --region eu-west-101 ap-southeast-1 # Environment variable (space- or comma-separated) export HUAWEICLOUD_REGION="ap-southeast-1, ap-southeast-2" prowler huaweicloud ``` ### Scan an Entire Cloud To scan every region of an account's cloud without listing regions, use the `--cloud` selector or the `HUAWEICLOUD_CLOUD` environment variable. Prowler expands it to that cloud's regions and selects the matching endpoint automatically: ```bash theme={null} # Scan all Huawei Cloud Europe regions (.eu endpoints) prowler huaweicloud --cloud europe # Scan all International regions (.com endpoints) prowler huaweicloud --cloud international # Scan all China regions (.com endpoints) prowler huaweicloud --cloud china ``` The `--cloud` flag accepts three values: `international`, `europe`, and `china`. The `HUAWEICLOUD_CLOUD` (or `HW_CLOUD`) environment variable additionally accepts the short aliases `intl`/`com` (International), `eu` (Europe), and `cn` (China). > [!NOTE] > > A single set of credentials belongs to one cloud, so `--cloud` selects which cloud to scan — it cannot authenticate against both `.com` and `.eu` at once. To scan accounts on different clouds, run Prowler once per account with that account's credentials. ### How Prowler Handles Regions and Endpoints Prowler manages several Huawei Cloud specifics automatically during a scan: * **Endpoint selection:** The endpoint domain (`.eu` or `.com`) is derived from each region, so every service targets the right cloud. This corrects services whose bundled metadata still points Europe regions at `.com`. * **Project resolution:** The per-region project ID is resolved automatically, so multi-region scans work without any project configuration. * **Credential validation:** Credentials are validated against a region in the account's cloud that exposes IAM, so validation succeeds even when the requested regions do not all offer IAM. * **Unsupported regions:** Any region a given service does not offer is skipped and logged, so scanning an entire cloud never fails on regions where a service is unavailable. ### Supported Regions Prowler recognizes the following region IDs, grouped by cloud. **International (`.com`)** | Region ID | Location | | - | - | | `ae-ad-1` | UAE (Abu Dhabi) | | `af-north-1` | Egypt (Cairo) | | `af-south-1` | South Africa | | `ap-southeast-1` | Hong Kong | | `ap-southeast-2` | Singapore | | `ap-southeast-3` | Thailand | | `ap-southeast-4` | Malaysia | | `ap-southeast-5` | Indonesia (Jakarta) | | `eu-west-0` | Ireland | | `la-north-2` | Mexico | | `la-south-2` | Chile (Santiago) | | `me-east-1` | UAE (Dubai) | | `my-kualalumpur-1` | Malaysia (Kuala Lumpur) | | `na-mexico-1` | Mexico (Mexico City) | | `ru-moscow-1` | Russia (Moscow-1) | | `sa-brazil-1` | Brazil | | `tr-west-1` | Türkiye (Istanbul) | **Huawei Cloud Europe (`.eu`)** | Region ID | Location | | - | - | | `eu-west-101` | Ireland (Dublin) | **China (`.com`)** | Region ID | Location | | - | - | | `cn-north-1` | China (Beijing-1) | | `cn-north-2` | China (Beijing-2) | | `cn-north-4` | China (Beijing-4) | | `cn-north-9` | China (Ulanqab) | | `cn-north-11` | China (Ulanqab-11) | | `cn-north-12` | China (Ulanqab-12) | | `cn-east-2` | China (Shanghai-2) | | `cn-east-3` | China (Shanghai-1) | | `cn-east-4` | China (Shanghai-4) | | `cn-east-5` | China (Shanghai-5) | | `cn-south-1` | China (Guangzhou) | | `cn-south-2` | China (Guangzhou-2) | | `cn-south-4` | China (Guangzhou-4) | | `cn-southwest-2` | China (Guiyang) | | `cn-southwest-3` | China (Guiyang-3) | ## Available Services Prowler for Huawei Cloud currently supports the following services: | Service | Description | | - | - | | `cts` | Cloud Trace Service trackers that record account and API activity for audit logging | | `ecs` | Elastic Cloud Server compute instances and their key pair, public IP, and security group configuration | | `elb` | Elastic Load Balance load balancers and their public exposure | | `evs` | Elastic Volume Service block volumes and their encryption settings | | `iam` | Identity and Access Management users, MFA devices, password policy, and account operation protection | | `kms` | Key Management Service keys, their state, and rotation configuration | | `obs` | Object Storage Service buckets and their public-access configuration | | `rds` | Relational Database Service instances and their public access, backup, and disk-encryption settings | | `vpc` | Virtual Private Cloud security groups and their ingress rules | | `waf` | Web Application Firewall instances and their status | # IaC Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/iac/authentication Prowler's Infrastructure as Code (IaC) provider enables you to scan local or remote infrastructure code for security and compliance issues using [Trivy](https://trivy.dev/). This provider supports a wide range of IaC frameworks and requires no cloud authentication for local scans. ### Authentication * For local scans, no authentication is required. * For remote repository scans, authentication can be provided via: * [**GitHub Username and Personal Access Token (PAT)**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) * [**GitHub OAuth App Token**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) * [**Git URL**](https://git-scm.com/docs/git-clone#_git_urls) ### Private Repository Hosts **Prowler CLI scans a repository on an internal network with no extra configuration.** On the CLI the operator supplies the repository URL themselves, so there is nothing to defend against and the check below does not apply. **Prowler App rejects a repository URL that resolves to a non-public address**, as an SSRF defense. There the URL arrives from a tenant and the worker must not be used to reach the internal network it runs in. The check covers both the connection test and the scan clone. To scan a self-hosted GitLab, Gitea or Bitbucket from Prowler App, declare the trusted ranges: ```console theme={null} PROWLER_ALLOWED_PRIVATE_NETWORKS="10.20.0.0/16,192.168.65.254/32" ``` The value is a comma-separated list of IPs and CIDRs. A resolved address inside an allowlisted range is permitted; every other non-public address stays blocked, so link-local (`169.254.169.254`), loopback and the rest of the internal network remain protected. Malformed entries are rejected, and a non-empty allowlist is logged as a relaxed security control. The scan runs in the worker, not the API, so the variable has to reach the worker: * **Docker Compose**: set it in the root `.env`; it reaches the worker through the shared environment file. * **Helm**: add it under `api.djangoConfig`, which is rendered into the API ConfigMap that the worker inherits through `envFrom`. ```yaml theme={null} api: djangoConfig: PROWLER_ALLOWED_PRIVATE_NETWORKS: "10.20.0.0/16" ``` Setting it only on the API container has no effect. The same variable applies to the Kubernetes and OpenStack providers. The Image provider has its own, `PROWLER_IMAGE_PROVIDER_ALLOWED_PRIVATE_NETWORKS`. # Getting Started with the IaC Provider Source: https://docs.prowler.com/user-guide/providers/iac/getting-started-iac Prowler's Infrastructure as Code (IaC) provider enables scanning of local or remote infrastructure code for security and compliance issues using [Trivy](https://trivy.dev/). This provider supports a wide range of IaC frameworks, allowing assessment of code before deployment. ## Supported IaC Formats Prowler IaC provider scans the following Infrastructure as Code configurations for misconfigurations and secrets: | Configuration Type | File Patterns | | - | - | | Kubernetes | `*.yml`, `*.yaml`, `*.json` | | Docker | `Dockerfile`, `Containerfile` | | Terraform | `*.tf`, `*.tf.json`, `*.tfvars` | | Terraform Plan | `tfplan`, `*.tfplan`, `*.json` | | CloudFormation | `*.yml`, `*.yaml`, `*.json` | | Azure ARM Template | `*.json` | | Helm | `*.yml`, `*.yaml`, `*.tpl`, `*.tar.gz`, etc. | | YAML | `*.yaml`, `*.yml` | | JSON | `*.json` | | Ansible | `*.yml`, `*.yaml`, `*.json`, `*.ini`, without extension | ## How It Works * Prowler Cloud leverages [Trivy](https://trivy.dev/docs/latest/guide/coverage/iac/#scanner) to scan local directories (or specified paths) for supported IaC files, or scans remote repositories. * No cloud credentials or authentication are required for local scans. * For remote repository scans, authentication can be provided via [git URL](https://git-scm.com/docs/git-clone#_git_urls), CLI flags or environment variables. * Check the [IaC Authentication](/user-guide/providers/iac/authentication) page for more details. * Mutelist logic ([filtering](https://trivy.dev/latest/docs/configuration/filtering/)) is handled by Trivy, not Prowler. * Results are output in the same formats as other Prowler providers (CSV, JSON-OCSF, HTML), plus [SARIF](/user-guide/cli/tutorials/reporting#sarif-iac-only) for GitHub Code Scanning integration. ## Prowler Cloud [Added in:  5.14.0](https://github.com/prowler-cloud/prowler/releases/tag/5.14.0) > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Supported Scanners Scanner selection is not configurable in Prowler Cloud. Default scanners, misconfig and secret, run automatically during each scan. ### Step 1: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Go to "Configuration" > "Providers" ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider" ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Infrastructure as Code" ![Select Infrastructure as Code](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/select-iac.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=d5151cee71f5bd0c46f5595f18af6960) 5. Add the Repository URL and an optional alias, then click "Next" ![Add IaC Repository URL](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/add-iac-repo.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=a5dc3a5ca2d4c587338374aee1861a50) ### Step 2: Enter Authentication Details 6. Optionally provide the [authentication](/user-guide/providers/iac/authentication) details for private repositories, then click "Next" ![IaC Authentication](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/iac-authentication.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=f59703ae2c47332315b76ac4ba64b619) ### Step 3: Verify Connection & Start Scan 7. Review the provider configuration and click "Launch scan" to initiate the scan ![Verify Connection & Start Scan](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/providers/iac-verify-connection.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=13700bd997b871af7a4831f0fac7279b) ## Prowler CLI [Added in:  5.8.0](https://github.com/prowler-cloud/prowler/releases/tag/5.8.0) ### Supported Scanners Prowler CLI supports the following scanners: * [Vulnerability](https://trivy.dev/docs/latest/guide/scanner/vulnerability/) * [Misconfiguration](https://trivy.dev/docs/latest/guide/scanner/misconfiguration/) * [Secret](https://trivy.dev/docs/latest/guide/scanner/secret/) * [License](https://trivy.dev/docs/latest/guide/scanner/license/) By default, only misconfiguration and secret scanners run during a scan. To specify which scanners to use, refer to the [Specify Scanners](#specify-scanners) section below. ### Usage Use the `iac` argument to run Prowler with the IaC provider. Specify the directory or repository to scan, frameworks to include, and paths to exclude. #### Scan a Local Directory (default) ```sh theme={null} prowler iac --scan-path ./my-iac-directory ``` #### Scan a Remote GitHub Repository ```sh theme={null} prowler iac --scan-repository-url https://github.com/user/repo.git ``` ##### Authentication for Remote Private Repositories Authentication for private repositories can be provided using one of the following methods: * **GitHub Username and Personal Access Token (PAT):** ```sh theme={null} prowler iac --scan-repository-url https://github.com/user/repo.git \ --github-username --personal-access-token ``` * **GitHub OAuth App Token:** ```sh theme={null} prowler iac --scan-repository-url https://github.com/user/repo.git \ --oauth-app-token ``` * If not provided via CLI, the following environment variables will be used (in order of precedence): * `GITHUB_OAUTH_APP_TOKEN` * `GITHUB_USERNAME` and `GITHUB_PERSONAL_ACCESS_TOKEN` * If neither CLI flags nor environment variables are set, the scan will attempt to clone without authentication or using the credentials provided in the [git URL](https://git-scm.com/docs/git-clone#_git_urls). ##### Mutually Exclusive Flags * `--scan-path` and `--scan-repository-url` are mutually exclusive. Only one can be specified at a time. #### Specify Scanners To run only specific scanners, use the `--scanners` flag. For example, to scan only for vulnerabilities and misconfigurations: ```sh theme={null} prowler iac --scan-path ./my-iac-directory --scanners vuln misconfig ``` #### Exclude Paths ```sh theme={null} prowler iac --scan-path ./my-iac-directory --exclude-path ./my-iac-directory/test ./my-iac-directory/examples ``` ### Output Use the standard Prowler output options. The IaC provider also supports [SARIF](/user-guide/cli/tutorials/reporting#sarif-iac-only) output for GitHub Code Scanning integration: ```sh theme={null} prowler iac --scan-path ./iac --output-formats csv json-ocsf html ``` #### SARIF Output [Added in:  5.25.0](https://github.com/prowler-cloud/prowler/releases/tag/5.25.0) To generate SARIF output for integration with SARIF-compatible tools: ```sh theme={null} prowler iac --scan-repository-url https://github.com/user/repo -M sarif ``` See the [SARIF reporting documentation](/user-guide/cli/tutorials/reporting#sarif-iac-only) for details on the format and severity mapping. # Image Authentication in Prowler Source: https://docs.prowler.com/user-guide/providers/image/authentication Prowler's Image provider enables container image security scanning using [Trivy](https://trivy.dev/). No authentication is required for public images. Prowler supports the following authentication methods for private registries: * [**Basic Authentication (Environment Variables)**](https://trivy.dev/latest/docs/advanced/private-registries/docker-hub/): `REGISTRY_USERNAME` and `REGISTRY_PASSWORD` * [**Token-Based Authentication**](https://distribution.github.io/distribution/spec/auth/token/): `REGISTRY_TOKEN` * [**Manual Docker Login**](https://docs.docker.com/reference/cli/docker/login/): Existing credentials in Docker's credential store Prowler uses the first available method in this priority order. ## Basic Authentication (Environment Variables) To authenticate with a username and password, set the `REGISTRY_USERNAME` and `REGISTRY_PASSWORD` environment variables. Prowler passes these credentials to Trivy, which handles authentication with the registry transparently: ```bash theme={null} export REGISTRY_USERNAME="myuser" export REGISTRY_PASSWORD="mypassword" prowler image -I myregistry.io/myapp:v1.0 ``` Both variables must be set for this method to activate. ## Token-Based Authentication To authenticate using a registry token (such as a bearer or OAuth2 token), set the `REGISTRY_TOKEN` environment variable. Prowler passes the token directly to Trivy: ```bash theme={null} export REGISTRY_TOKEN="my-registry-token" prowler image -I myregistry.io/myapp:v1.0 ``` This method is useful for registries that support token-based access without requiring a username and password. ## Manual Docker Login (Fallback) If no environment variables are set, Prowler relies on existing credentials in Docker's credential store (`~/.docker/config.json`). To configure credentials manually before scanning: ```bash theme={null} docker login myregistry.io prowler image -I myregistry.io/myapp:v1.0 ``` > [!NOTE] > > This method is available in Prowler CLI only. In Prowler Cloud, use basic authentication or token-based authentication instead. # Getting Started with the Image Provider Source: https://docs.prowler.com/user-guide/providers/image/getting-started-image Prowler's Image provider enables comprehensive container image security scanning by integrating with [Trivy](https://trivy.dev/). This provider detects vulnerabilities, exposed secrets, and misconfigurations in container images, converting Trivy findings into Prowler's standard reporting format for unified security assessment. ## How It Works * **Trivy integration:** Prowler leverages [Trivy](https://trivy.dev/) to scan container images for vulnerabilities, secrets, misconfigurations, and license issues. * **Authentication:** No registry authentication is required for public images. For private registries, credentials can be provided via environment variables or manual `docker login`. * Check the [Image Authentication](/user-guide/providers/image/authentication) page for more details. * **Mutelist logic:** [Filtering](https://trivy.dev/latest/docs/configuration/filtering/) is handled by Trivy, not Prowler. * **Output formats:** Results are output in the same formats as other Prowler providers (CSV, JSON, HTML, etc.). > [card] [Prowler Cloud](#prowler-cloud) > > Scan container images using Prowler Cloud > [card] [Prowler CLI](#prowler-cli) > > Scan container images using Prowler CLI ## Prowler Cloud [Added in:  5.21.0](https://github.com/prowler-cloud/prowler/releases/tag/5.21.0) > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Supported Scanners Prowler Cloud does not support scanner selection. The vulnerability, secret, and misconfiguration scanners run automatically during each scan. ### Step 1: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Navigate to "Configuration" > "Providers" ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider" ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Container Registry" ![Select Container Registry](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/user-guide/img/select-container-registry.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=0e6dd3f4a23d1960e7df0c6637086c17) 5. Enter the container registry URL (e.g., `docker.io/myorg` or `myregistry.io`) and an optional alias, then click "Next" ![Add Container Registry URL](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/user-guide/img/add-registry-url.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=aacd760bb78e26d1f301293ade5c0344) ### Step 2: Enter Authentication and Scan Filters 6. Optionally provide [authentication](/user-guide/providers/image/authentication) credentials for private registries, then configure the following scan filters to control which images are scanned: * **Image filter:** A regex pattern to filter repositories by name (e.g., `^prod/.*`) * **Tag filter:** A regex pattern to filter tags within repositories (e.g., `^(latest|v\d+\.\d+\.\d+)$`) Then click "Next" ![Image Authentication and Filters](https://mintcdn.com/prowler/vG8-bmatEv1C0Qk6/user-guide/img/image-authentication-filters.png?fit=max\&auto=format\&n=vG8-bmatEv1C0Qk6\&q=85\&s=4659e87b6435486c384c565688bbd85a) ### Step 3: Verify Connection & Start Scan 7. Review the provider configuration and click "Launch scan" to initiate the scan ![Verify Connection & Start Scan](https://mintcdn.com/prowler/zwl1yuNp_nMNJ1vL/user-guide/img/image-verify-connection.png?fit=max\&auto=format\&n=zwl1yuNp_nMNJ1vL\&q=85\&s=b2897a926be13c6a890430abc631c19c) ## Prowler CLI [Added in:  5.19.0](https://github.com/prowler-cloud/prowler/releases/tag/5.19.0) ### Install Trivy Install Trivy using one of the following methods: > [tab] Homebrew > > ```bash theme={null} > brew install trivy > ``` > [tab] apt (Debian/Ubuntu) > > ```bash theme={null} > sudo apt-get install trivy > ``` > [tab] Install Script > > ```bash theme={null} > curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin > ``` For additional installation methods, see the [Trivy installation guide](https://trivy.dev/latest/getting-started/installation/). ### Vulnerability Database Cache [Added in:  5.42.0](https://github.com/prowler-cloud/prowler/releases/tag/5.42.0) Trivy keeps its vulnerability database in a cache directory. By default Prowler gives it a temporary one and removes it when the scan ends, so the database is downloaded again for every scan. Set `TRIVY_CACHE_DIR` to a directory that persists and the database is downloaded once and reused: ```bash theme={null} export TRIVY_CACHE_DIR="$HOME/.cache/trivy" prowler image --image ``` Prowler never deletes a directory you supply. Trivy still creates and updates its cache and database files inside it. > [!NOTE] > > A host with no internet access needs a pre-populated vulnerability database in a persistent directory, with `TRIVY_CACHE_DIR` pointing at it. Populate the directory on a machine that does have access and copy it across. > > Trivy tries to refresh the database when it considers it stale, and that download fails without network access. Set `TRIVY_SKIP_DB_UPDATE=true` (and `TRIVY_SKIP_JAVA_DB_UPDATE=true` if Java scanning is enabled) so it uses the supplied database as is. > > The database ages. A scan run against an old one reports only the vulnerabilities known when it was built, and nothing in the output says so, so keep track of when it was last refreshed. ### Supported Scanners Prowler CLI supports the following scanners: * [Vulnerability](https://trivy.dev/docs/latest/guide/scanner/vulnerability/) * [Secret](https://trivy.dev/docs/latest/guide/scanner/secret/) * [Misconfiguration](https://trivy.dev/docs/latest/guide/scanner/misconfiguration/) * [License](https://trivy.dev/docs/latest/guide/scanner/license/) By default, vulnerability, secret, and misconfiguration scanners run during a scan. To specify which scanners to use, refer to the [Specify Scanners](#specify-scanners) section below. ### Scan Container Images Use the `image` argument to run Prowler with the Image provider. Specify the images to scan using the `-I` flag or an image list file. #### Scan a Single Image To scan a single container image: ```bash theme={null} prowler image -I alpine:3.18 ``` #### Scan Multiple Images To scan multiple images, repeat the `-I` flag: ```bash theme={null} prowler image -I nginx:latest -I redis:7 -I python:3.12-slim ``` #### Scan From an Image List File For large-scale scanning, provide a file containing one image per line: ```bash theme={null} prowler image --image-list images.txt ``` The file supports comments (lines starting with `#`) and blank lines: ```text theme={null} # Production images nginx:1.25 redis:7-alpine # Development images python:3.12-slim node:20-bookworm ``` > [!NOTE] > > Image list files are limited to a maximum of 10,000 lines. Individual image names exceeding 500 characters are automatically skipped with a warning. > [!WARNING] > > Image names must follow the Open Container Initiative (OCI) reference format. Valid names start with an alphanumeric character and contain only letters, digits, periods, hyphens, underscores, slashes, colons, and `@` symbols. Names containing shell metacharacters (`;`, `|`, `&`, `$`, `` ` ``) are rejected to prevent command injection. Valid examples: * **Standard tag:** `alpine:3.18` * **Custom registry:** `myregistry.io/myapp:v1.0` * **SHA digest:** `ghcr.io/org/image@sha256:abc123...` #### Specify Scanners To select which scanners Trivy runs, use the `--scanners` option: ```bash theme={null} # Vulnerability scanning only prowler image -I alpine:3.18 --scanners vuln # All available scanners prowler image -I alpine:3.18 --scanners vuln secret misconfig license ``` #### Image Config Scanners To scan Dockerfile-level metadata for misconfigurations or embedded secrets, use the `--image-config-scanners` option: ```bash theme={null} # Scan Dockerfile for misconfigurations prowler image -I alpine:3.18 --image-config-scanners misconfig # Scan Dockerfile for both misconfigurations and secrets prowler image -I alpine:3.18 --image-config-scanners misconfig secret ``` Available image config scanners: * **misconfig**: Detects Dockerfile misconfigurations (e.g., running as root, missing health checks) * **secret**: Identifies secrets embedded in Dockerfile instructions > [!NOTE] > > Image config scanners are disabled by default. This option is independent from `--scanners` and specifically targets the image configuration (Dockerfile) rather than the image filesystem. #### Filter by Severity To filter findings by severity level, use the `--trivy-severity` option: ```bash theme={null} # Only critical and high severity findings prowler image -I alpine:3.18 --trivy-severity CRITICAL HIGH ``` Available severity levels: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`. #### Ignore Unfixed Vulnerabilities To exclude vulnerabilities without available fixes: ```bash theme={null} prowler image -I alpine:3.18 --ignore-unfixed ``` #### Configure Scan Timeout To adjust the scan timeout for large images or slow network conditions, use the `--timeout` option: ```bash theme={null} prowler image -I large-image:latest --timeout 10m ``` The timeout accepts values in seconds (`s`), minutes (`m`), or hours (`h`). Default: `5m`. ### Registry Scan Mode Registry Scan Mode enumerates and scans all images from an OCI-compatible registry, Docker Hub namespace, or Amazon ECR registry. To activate it, use the `--registry` flag with the registry URL: ```bash theme={null} prowler image --registry myregistry.io ``` #### Discover Available Images To list all repositories and tags available in the registry without running a scan, use the `--registry-list` flag. This is useful for discovering image names and tags before building filter regexes: ```bash theme={null} prowler image --registry myregistry.io --registry-list ``` Example output: ```text theme={null} Registry: myregistry.io (3 repositories, 8 images) api-service (2 tags) latest, v3.1 hub-scanner (3 tags) latest, v1.0, v2.0 web-frontend (3 tags) latest, v1.0, v2.0 ``` Filters can be combined with `--registry-list` to preview the results before scanning: ```bash theme={null} prowler image --registry myregistry.io --registry-list --image-filter "api.*" ``` #### Filter Repositories To filter repositories by name during enumeration, use the `--image-filter` flag with a Python regex pattern (matched via `re.search`): ```bash theme={null} # Scan only repositories starting with "prod/" prowler image --registry myregistry.io --image-filter "^prod/" ``` #### Filter Tags To filter tags during enumeration, use the `--tag-filter` flag with a Python regex pattern: ```bash theme={null} # Scan only semantic version tags prowler image --registry myregistry.io --tag-filter "^v\d+\.\d+\.\d+$" ``` Both filters can be combined: ```bash theme={null} prowler image --registry myregistry.io --image-filter "^prod/" --tag-filter "^(latest|v\d+)" ``` #### Limit the Number of Images To prevent accidentally scanning a large number of images, use the `--max-images` flag. The scan aborts if the discovered image count exceeds the limit: ```bash theme={null} prowler image --registry myregistry.io --max-images 10 ``` Setting `--max-images` to `0` (default) disables the limit. > [!NOTE] > > When `--registry-list` is active, the `--max-images` limit is not enforced because no scan is performed. #### Skip TLS Verification To connect to registries with self-signed certificates, use the `--registry-insecure` flag: ```bash theme={null} prowler image --registry internal-registry.local --registry-insecure ``` > [!WARNING] > > Skipping TLS verification disables certificate validation for registry connections, including the Trivy image pull (`TRIVY_INSECURE`). Use this flag only for trusted internal registries with self-signed certificates. #### On-Premises Registries and Private Networks [Added in:  5.41.0](https://github.com/prowler-cloud/prowler/releases/tag/5.41.0) By default, Prowler rejects registry-provided URLs (token endpoints, pagination links) that resolve to non-public addresses, as an SSRF defense. On-premises registries live on private networks by definition, so to scan them declare the trusted ranges explicitly: ```bash theme={null} export PROWLER_IMAGE_PROVIDER_ALLOWED_PRIVATE_NETWORKS="192.168.65.254/32,10.20.0.0/16" ``` The value is a comma-separated list of IPs and CIDRs. A resolved address inside an allowlisted range is permitted; every other non-public address stays blocked, so link-local (`169.254.169.254`), loopback, and the rest of the internal network remain protected. The variable applies to registry enumeration and to the connection test. Malformed entries fail at startup, and a non-empty allowlist is logged as a relaxed security control. When unset, behavior is unchanged: only public addresses are followed. #### Supported Registries Registry Scan Mode supports the following registry types: * **OCI-compatible registries:** Any registry implementing the OCI Distribution Specification (e.g., Harbor, GitLab Container Registry, GitHub Container Registry). * **Docker Hub:** Specify a namespace with `--registry docker.io/{org_or_user}`. Public namespaces can be scanned without credentials; authenticated access is used automatically when `REGISTRY_USERNAME` and `REGISTRY_PASSWORD` are set. * **Amazon ECR:** Use the full ECR endpoint URL (e.g., `123456789.dkr.ecr.us-east-1.amazonaws.com`). Authentication is handled via AWS credentials. ### Authentication for Private Registries To scan images from private registries, the Image provider supports three authentication methods. Prowler uses the first available method in this priority order: #### 1. Basic Authentication (Environment Variables) To authenticate with a username and password, set the `REGISTRY_USERNAME` and `REGISTRY_PASSWORD` environment variables. Prowler passes these credentials to Trivy, which handles authentication with the registry transparently: ```bash theme={null} export REGISTRY_USERNAME="myuser" export REGISTRY_PASSWORD="mypassword" prowler image -I myregistry.io/myapp:v1.0 ``` Both variables must be set for this method to activate. #### 2. Token-Based Authentication To authenticate using a registry token (such as a bearer or OAuth2 token), set the `REGISTRY_TOKEN` environment variable. Prowler passes the token directly to Trivy: ```bash theme={null} export REGISTRY_TOKEN="my-registry-token" prowler image -I myregistry.io/myapp:v1.0 ``` This method is useful for registries that support token-based access without requiring a username and password. #### 3. Manual Docker Login (Fallback) If no environment variables are set, Prowler relies on existing credentials in Docker's credential store (`~/.docker/config.json`). To configure credentials manually before scanning: ```bash theme={null} docker login myregistry.io prowler image -I myregistry.io/myapp:v1.0 ``` > [!NOTE] > > Credentials provided via environment variables are only passed to the Trivy subprocess and are not persisted beyond the scan. ### Troubleshooting Common Scan Errors The Image provider categorizes common Trivy errors with actionable guidance: * **Authentication failure (401/403):** Registry credentials are missing or invalid. Verify the `REGISTRY_USERNAME`/`REGISTRY_PASSWORD` or `REGISTRY_TOKEN` environment variables, or run `docker login` for the target registry and retry the scan. * **Image not found (404):** The specified image name, tag, or registry is incorrect. Verify the image reference exists and is accessible. * **Rate limited (429):** The container registry is throttling requests. Wait before retrying, or authenticate to increase rate limits. * **Network issue:** Trivy cannot reach the registry due to connectivity problems. Check network access, DNS resolution, and firewall rules. # Getting Started with Kubernetes Source: https://docs.prowler.com/user-guide/providers/kubernetes/getting-started-k8s ## Prowler Cloud > [!NOTE] > > This guide applies to > > . See [Prowler product families](/getting-started/products). ### Step 1: Access Prowler Cloud 1. Sign in to [Prowler Cloud](https://cloud.prowler.com/sign-in) or [create an account](https://cloud.prowler.com/sign-up) 2. Go to "Configuration" > "Providers" ![Providers Page](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/cloud-providers-page.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=aa592727864e8328ab2574708df74d34) 3. Click "Add Provider" ![Add a Provider](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/prowler-app/add-cloud-provider.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=793e5a073e1a037e453df158ad7b854d) 4. Select "Kubernetes" 5. Enter your Kubernetes Cluster context from your kubeconfig file and optionally provide a friendly alias ### Step 2: Configure Kubernetes Authentication For Kubernetes, Prowler Cloud uses a `kubeconfig` file to authenticate. Paste the contents of your `kubeconfig` file into the `Kubeconfig content` field. > [!NOTE] > > Only inline kubeconfig credentials are supported: `token`, `username`/`password`, or `client-certificate-data` with `client-key-data` for users, and `certificate-authority-data` for clusters. Kubeconfigs that reference external files (`tokenFile`, `client-certificate`, `client-key`, `certificate-authority`), run commands (`exec`, `cmd-path`), use `auth-provider` directives, set a proxy URL, or include unsupported user or cluster fields are rejected. Impersonation fields (`as`, `as-uid`, `as-groups`, `as-user-extra`) are accepted but not applied, so Prowler connects with the identity of the user credentials. Use inline credentials such as the ServiceAccount token flow documented below. By default, the `kubeconfig` file is located at `~/.kube/config`. ![Kubernetes Credentials](https://mintcdn.com/prowler/yyJURFHpPIAaK8F3/images/kubernetes-credentials.png?fit=max\&auto=format\&n=yyJURFHpPIAaK8F3\&q=85\&s=f8872d0a2be2393bb41b88b78ac1a95e) ### Step 3: Additional Setup for EKS, GKE, AKS, or External Clusters If you are adding an **EKS**, **GKE**, **AKS** or external cluster, follow these additional steps to ensure proper authentication: **Make sure your cluster allows traffic from the Prowler Cloud IP address `52.48.254.174/32`** 1. Apply the necessary Kubernetes resources to your EKS, GKE, AKS or external cluster (you can find the files in the [`kubernetes` directory of the Prowler repository](https://github.com/prowler-cloud/prowler/tree/master/kubernetes)): ```console theme={null} kubectl apply -f kubernetes/prowler-sa.yaml kubectl apply -f kubernetes/prowler-role.yaml kubectl apply -f kubernetes/prowler-rolebinding.yaml ``` 2. Generate a long-lived token for authentication: ```console theme={null} kubectl create token prowler-sa -n prowler-ns --duration=0 ``` * **Security Note:** The `--duration=0` option generates a non-expiring token, which may pose a security risk if not managed properly. Choose an appropriate expiration time based on security policies. For a limited-time token, set `--duration=