From 51c65bdc69162e3f94922e834eaecf58983cfa60 Mon Sep 17 00:00:00 2001 From: Hugo Pereira Brito <101209179+HugoPBrito@users.noreply.github.com> Date: Tue, 25 Aug 2026 12:49:23 +0100 Subject: [PATCH] docs: restructure organization documentation (#12521) --- docs/docs.json | 10 ++++ docs/user-guide/organizations.mdx | 58 +++++++++++++++++++ .../providers/aws/organizations.mdx | 2 + .../providers/azure/management-groups.mdx | 53 +++++++++++++++++ .../providers/azure/subscriptions.mdx | 12 +--- .../user-guide/providers/gcp/organization.mdx | 2 + .../aws-organizations-bulk-provisioning.mdx | 2 + .../prowler-cloud-aws-organizations.mdx | 2 + 8 files changed, 130 insertions(+), 11 deletions(-) create mode 100644 docs/user-guide/organizations.mdx create mode 100644 docs/user-guide/providers/azure/management-groups.mdx diff --git a/docs/docs.json b/docs/docs.json index 363d6ac082..a784b2e17e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -301,6 +301,15 @@ { "group": "Providers", "pages": [ + { + "group": "Organizations", + "pages": [ + "user-guide/organizations", + "user-guide/providers/aws/organizations", + "user-guide/providers/gcp/organization", + "user-guide/providers/azure/management-groups" + ] + }, { "group": "Alibaba Cloud", "pages": [ @@ -330,6 +339,7 @@ "user-guide/providers/azure/getting-started-azure", "user-guide/providers/azure/authentication", "user-guide/providers/azure/use-non-default-cloud", + "user-guide/providers/azure/management-groups", "user-guide/providers/azure/subscriptions", "user-guide/providers/azure/resource-groups", "user-guide/providers/azure/create-prowler-service-principal" diff --git a/docs/user-guide/organizations.mdx b/docs/user-guide/organizations.mdx new file mode 100644 index 0000000000..39377483de --- /dev/null +++ b/docs/user-guide/organizations.mdx @@ -0,0 +1,58 @@ +--- +title: 'Organizations Across Cloud Providers' +description: '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. + + +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. diff --git a/docs/user-guide/providers/aws/organizations.mdx b/docs/user-guide/providers/aws/organizations.mdx index b48df1c442..92a4faf2ae 100644 --- a/docs/user-guide/providers/aws/organizations.mdx +++ b/docs/user-guide/providers/aws/organizations.mdx @@ -12,6 +12,8 @@ See [AWS Organizations](/user-guide/tutorials/prowler-cloud-aws-organizations) i 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**. diff --git a/docs/user-guide/providers/azure/management-groups.mdx b/docs/user-guide/providers/azure/management-groups.mdx new file mode 100644 index 0000000000..5131defc7d --- /dev/null +++ b/docs/user-guide/providers/azure/management-groups.mdx @@ -0,0 +1,53 @@ +--- +title: 'Azure Management Groups in Prowler' +--- + +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](/images/create-management-group.gif) + +After creating the management group, add the subscriptions that Prowler should access and scan. + +![Add Subscription to Management Group](/images/add-sub-to-management-group.gif) + +## 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. diff --git a/docs/user-guide/providers/azure/subscriptions.mdx b/docs/user-guide/providers/azure/subscriptions.mdx index efd37c13e5..e86101990e 100644 --- a/docs/user-guide/providers/azure/subscriptions.mdx +++ b/docs/user-guide/providers/azure/subscriptions.mdx @@ -25,14 +25,4 @@ Check the [Authentication > Subscription Scope Permissions](/user-guide/provider ## 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 management groups in Azure. This approach allows Prowler to efficiently organize and audit multiple subscriptions collectively. - -1. **Create a Management Group**: Follow the [official guide](https://learn.microsoft.com/en-us/azure/governance/management-groups/create-management-group-portal) to create a new management group. - - ![Create management group](/images/create-management-group.gif) - -2. **Assign Roles**: Assign necessary roles to the management group, similar to the [role assignment process](#assigning-permissions-for-subscription-scans). - - Role assignment should be done at the management group level instead of per subscription. - -3. **Add Subscriptions**: Add all subscriptions you want to audit to the newly created management group. ![Add Subscription to Management Group](/images/add-sub-to-management-group.gif) +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. diff --git a/docs/user-guide/providers/gcp/organization.mdx b/docs/user-guide/providers/gcp/organization.mdx index 6790be5827..fe488ee6e5 100644 --- a/docs/user-guide/providers/gcp/organization.mdx +++ b/docs/user-guide/providers/gcp/organization.mdx @@ -4,6 +4,8 @@ title: 'Scanning a Specific 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 diff --git a/docs/user-guide/tutorials/aws-organizations-bulk-provisioning.mdx b/docs/user-guide/tutorials/aws-organizations-bulk-provisioning.mdx index 188ac3540d..9217c28b0a 100644 --- a/docs/user-guide/tutorials/aws-organizations-bulk-provisioning.mdx +++ b/docs/user-guide/tutorials/aws-organizations-bulk-provisioning.mdx @@ -4,6 +4,8 @@ title: 'AWS Organizations Bulk Provisioning in Prowler' Prowler offers an automated tool to discover and provision all AWS accounts within an AWS Organization. This streamlines onboarding for organizations managing multiple AWS accounts by automatically generating the configuration needed for bulk provisioning. +For the cross-provider organization lifecycle and terminology, see [Organizations Across Cloud Providers](/user-guide/organizations). + The tool, `aws_org_generator.py`‎, complements the [Bulk Provider Provisioning](./bulk-provider-provisioning) tool and is available in the Prowler repository at: [util/prowler-bulk-provisioning](https://github.com/prowler-cloud/prowler/tree/master/util/prowler-bulk-provisioning) diff --git a/docs/user-guide/tutorials/prowler-cloud-aws-organizations.mdx b/docs/user-guide/tutorials/prowler-cloud-aws-organizations.mdx index c17be7b976..9454929360 100644 --- a/docs/user-guide/tutorials/prowler-cloud-aws-organizations.mdx +++ b/docs/user-guide/tutorials/prowler-cloud-aws-organizations.mdx @@ -10,6 +10,8 @@ import { SubscriptionBanner } from "/snippets/subscription-banner.mdx" Prowler Cloud onboards every AWS account in your Organization through a single guided wizard. Instead of connecting accounts one by one, you can discover every account in your AWS Organization, select the ones you want to monitor, test connectivity, and launch scans — all from the Prowler Cloud UI. +For the cross-provider organization lifecycle and terminology, see [Organizations Across Cloud Providers](/user-guide/organizations). + For CLI-based multi-account scanning, see [AWS Organizations in Prowler CLI](/user-guide/providers/aws/organizations).