mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-07-23 20:42:02 +00:00
feat(ui): one-step AWS Organizations onboarding + S3 bucket acc (#11927)
Co-authored-by: alejandrobailo <alejandrobailo94@gmail.com> Co-authored-by: Pablo F.G <pablo.fernandez@prowler.com> Co-authored-by: Daniel Barranquero <danielbo2001@gmail.com>
This commit is contained in:
Pedro Martín
@@ -272,6 +272,8 @@ python aws_org_generator.py \
|
||||
4. Deploy to all organizational units
|
||||
5. Use a unique external ID (e.g., `prowler-org-2024-abc123`)
|
||||
|
||||
Alternatively, deploy the same template as a **single stack** with `DeployStackSet=true` and `AWSOrganizationalUnitId` set to your root/OU ID — it creates the StackSet for you. See [Native CloudFormation StackSet Deployment](../providers/aws/organizations#native-cloudformation-stackset-deployment-recommended).
|
||||
|
||||
{/* TODO: Add screenshot of CloudFormation StackSets deployment */}
|
||||
</Step>
|
||||
|
||||
|
||||
@@ -25,10 +25,10 @@ For CLI-based multi-account scanning, see [AWS Organizations in Prowler CLI](/us
|
||||
|
||||
### How It Works
|
||||
|
||||
Before using the AWS Organizations wizard, you need to deploy **two Identity and Access Management (IAM) roles** in your AWS environment. The onboarding follows this sequence:
|
||||
Onboarding deploys the **ProwlerScan Identity and Access Management (IAM) role** in your management account and in every member account. The wizard can deploy both from a **single CloudFormation stack** ([Step 4](#step-4-authenticate-with-your-management-account)), or you can deploy them yourself beforehand using Steps 1–2. The onboarding follows this sequence:
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/onboarding-flow.svg" alt="Onboarding flow: 1. Create Management Account Role (Quick Create or Manual), 2. Deploy StackSet, 3. Run the Wizard, 4. Launch Scans" />
|
||||
<img src="/images/organizations/onboarding-flow.svg" alt="Onboarding flow: 1. Start the Wizard, 2. Deploy the Roles (single CloudFormation stack), 3. Discover and Connect, 4. Launch Scans" />
|
||||
</Frame>
|
||||
|
||||
## Key Concepts
|
||||
@@ -47,8 +47,8 @@ Prowler requires **two separate IAM roles** deployed in different places, each w
|
||||
|
||||
| Role | Where it lives | What it does | How to deploy it |
|
||||
|------|---------------|--------------|------------------|
|
||||
| **ProwlerScan** (management account) | Your management (root) account only | Discovers the Organization structure **and** scans the management account. Has additional Organizations discovery permissions. | Via **Quick Create** link or **manually** in the IAM Console ([Step 1](#step-1-create-the-management-account-role)). Cannot be deployed via StackSet. |
|
||||
| **ProwlerScan** (member accounts) | Every member account | Scans the account for security findings. | Via **CloudFormation StackSet** ([Step 2](#step-2-deploy-the-cloudformation-stackset)). Automated across all accounts. |
|
||||
| **ProwlerScan** (management account) | Your management (root) account only | Discovers the Organization structure **and** scans the management account. Has additional Organizations discovery permissions. | By the wizard's **single stack** ([Step 4](#step-4-authenticate-with-your-management-account)), or on its own via **Quick Create** link or **manually** in the IAM Console ([Step 1](#step-1-create-the-management-account-role)). Cannot be deployed via StackSet. |
|
||||
| **ProwlerScan** (member accounts) | Every member account | Scans the account for security findings. | By the wizard's **single stack** ([Step 4](#step-4-authenticate-with-your-management-account)), or on its own via a **CloudFormation StackSet** ([Step 2](#step-2-deploy-the-cloudformation-stackset)). Automated across all accounts. |
|
||||
|
||||
<Frame caption="Both roles share the same name `ProwlerScan`. The management account role includes additional Organization discovery permissions.">
|
||||
<img src="/images/organizations/two-roles-architecture.svg" alt="Two Roles Architecture: ProwlerScan in management account (Quick Create or Manual, discovery + scanning) and ProwlerScan in member accounts (via StackSet, scanning only)" />
|
||||
@@ -77,7 +77,7 @@ Your AWS environment must have [AWS Organizations](https://docs.aws.amazon.com/o
|
||||
The first role you need to create is the **management account role**. This role allows Prowler to discover your Organization structure — listing accounts, OUs, and hierarchy.
|
||||
|
||||
<Warning>
|
||||
**StackSets do not deploy to the management account.** Organizational CloudFormation StackSets with service-managed permissions only target member accounts — this is an AWS limitation, not a Prowler one. You must create the management account role separately, either via the Quick Create link ([Option A](#option-a-quick-create-link-fastest)) or manually ([Option B](#option-b-create-the-role-manually)).
|
||||
**StackSets do not deploy to the management account.** Organizational CloudFormation StackSets with service-managed permissions only target member accounts — this is an AWS limitation, not a Prowler one. The Prowler wizard works around this by having the **same** stack create the management account role (`DeployLocalRole=true`) alongside the StackSet, so a single deployment covers both. You can also create the management account role on its own via the Quick Create link ([Option A](#option-a-quick-create-link-fastest)) or manually ([Option B](#option-b-create-the-role-manually)).
|
||||
</Warning>
|
||||
|
||||
<Note>
|
||||
@@ -191,7 +191,7 @@ If you just created the role, it may take up to **60 seconds** for AWS to propag
|
||||
|
||||
## Step 2: Deploy the CloudFormation StackSet
|
||||
|
||||
After creating the management account role, the next step is to deploy the **ProwlerScan** role to your member accounts using a CloudFormation StackSet. This is the recommended method for consistent, scalable deployment across your entire organization.
|
||||
This step deploys the **ProwlerScan** role to your member accounts using a CloudFormation StackSet. It is the **manual alternative** to letting the wizard's single stack create the StackSet for you ([Step 4](#step-4-authenticate-with-your-management-account)) — use it if you prefer to create and manage the StackSet yourself.
|
||||
|
||||
The StackSet uses **service-managed permissions**, which means AWS Organizations handles the cross-account deployment automatically — you don't need to create execution roles manually in each account. The StackSet deploys the ProwlerScan IAM role in every target member account, enabling Prowler to assume that role for cross-account scanning.
|
||||
|
||||
@@ -199,9 +199,9 @@ The StackSet uses **service-managed permissions**, which means AWS Organizations
|
||||
**Trusted access required:** CloudFormation StackSets must have trusted access enabled in your management account. Verify this in the AWS Console under **AWS Organizations > Settings > Trusted access for AWS CloudFormation StackSets**.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
**The Quick Create link creates a Stack, not a StackSet.** The link in the Prowler wizard creates a CloudFormation **Stack** that deploys the ProwlerScan role in your management account only ([Step 1](#step-1-create-the-management-account-role)). To deploy the role across **member accounts**, you must create a StackSet manually as described below. AWS does not support Quick Create links for StackSets.
|
||||
</Warning>
|
||||
<Note>
|
||||
**The Prowler wizard now deploys this StackSet for you.** The **Create Stack in Management Account** button ([Step 4](#step-4-authenticate-with-your-management-account)) launches a single CloudFormation Stack that creates the management account role **and** a service-managed StackSet for your member accounts (`DeployStackSet=true`). Use the manual console steps below only if you prefer to create the StackSet yourself.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
**[Open StackSets Console →](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacksets/create)**
|
||||
@@ -243,7 +243,7 @@ Deployment typically takes **2–5 minutes** for medium-sized organizations. Lar
|
||||
|
||||
## Step 3: Start the Organization Wizard
|
||||
|
||||
Now that both roles are deployed — the management account role (Step 1) and the ProwlerScan role in member accounts (Step 2) — you can start the Prowler wizard.
|
||||
Start the Prowler wizard. It walks you through deploying both roles — the management account role and the ProwlerScan role in member accounts — from a single CloudFormation stack ([Step 4](#step-4-authenticate-with-your-management-account)). If you already deployed them beforehand via Steps 1–2, the wizard simply picks up where you left off.
|
||||
|
||||
### Open the Wizard
|
||||
|
||||
@@ -282,27 +282,46 @@ Click **Next** to proceed to the authentication phase.
|
||||
|
||||
## Step 4: Authenticate with Your Management Account
|
||||
|
||||
The wizard's **Authentication Details** page guides you through three actions: deploying the roles in AWS, entering the management account Role ARN, and confirming the deployment.
|
||||
The wizard's **Authentication Details** page guides you through three actions: deploying the roles in AWS, entering the deployment account Role ARN, and confirming the deployment. The deployment account is either the management account or, when delegated administrator mode is selected, the delegated administrator account.
|
||||
|
||||
### External ID
|
||||
|
||||
The wizard displays a **Prowler External ID** at the top — auto-generated and unique to your tenant. Click the copy icon to copy it. You will need this External ID for both the management account Stack and the member accounts StackSet.
|
||||
The wizard displays a **Prowler External ID** at the top — auto-generated and unique to your tenant. Click the copy icon to copy it. The External ID is pre-filled into the deployment link, and the single stack applies it to both the management account role and the member-account StackSet.
|
||||
|
||||
### Deploy the Roles
|
||||
|
||||
The wizard provides two deployment actions:
|
||||
<VersionBadge version="5.35.0" />
|
||||
|
||||
1. **Create Stack in Management Account** — opens a Quick Create link that deploys the ProwlerScan role with `EnableOrganizations=true` in your management account ([Step 1](#step-1-create-the-management-account-role)). The External ID is pre-filled.
|
||||
The wizard deploys the deployment account role and the member-account StackSet in a **single** CloudFormation Stack:
|
||||
|
||||
2. **Open StackSets Console** — links to the CloudFormation StackSets console where you create a StackSet for member accounts ([Step 2](#step-2-deploy-the-cloudformation-stackset)). Copy the template URL shown in the wizard and paste the External ID manually.
|
||||
1. **Organizational Unit or Root ID** — enter the AWS OU (`ou-xxxx-yyyyyyyy`) or organization root (`r-xxxx`) you want to onboard. Prowler rolls the ProwlerScan role out to every member account under this target. Find it in the [AWS Organizations Console](https://console.aws.amazon.com/organizations/); use the **root ID** (`r-`) to cover the entire organization or an **OU ID** (`ou-`) to target a specific unit.
|
||||
|
||||
2. *(Optional)* Check **"I'm deploying from a delegated administrator account"** if you launch the stack from a delegated administrator account instead of the management account.
|
||||
|
||||
3. **Create Stack in Management Account** — or **Create Stack in Delegated Administrator Account** when delegated administrator mode is selected — opens a Quick Create link that deploys, in a single stack: the ProwlerScan role in the account where you launch the stack (`DeployLocalRole`, with `EnableOrganizations=true`) **and** a service-managed StackSet (`DeployStackSet`) that rolls the role out to your member accounts. The External ID, OU/Root ID, and deployment options are pre-filled.
|
||||
|
||||
<Tip>
|
||||
**Finding your Organizational Unit or Root ID.** In the [AWS Organizations Console](https://console.aws.amazon.com/organizations/) the root (`r-…`) and OU (`ou-…`) IDs appear in the account tree, or run these from your management account:
|
||||
|
||||
```bash
|
||||
# Root ID — deploys the role to the entire organization
|
||||
aws organizations list-roots --query 'Roots[0].Id' --output text
|
||||
|
||||
# OU IDs under the root — to target a specific unit instead
|
||||
aws organizations list-organizational-units-for-parent --parent-id r-xxxx \
|
||||
--query 'OrganizationalUnits[].{Name:Name,Id:Id}' --output table
|
||||
```
|
||||
|
||||
If you deploy the CloudFormation template manually (instead of via the wizard link), set **`DeployStackSet=true`**, **`DeployLocalRole=true`**, and **`EnableOrganizations=true`**, then put the root/OU ID above into **`AWSOrganizationalUnitId`** (required whenever `DeployStackSet=true`). Leave **`DeployFromDelegatedAdmin=false`** unless you launch the stack from a delegated administrator account.
|
||||
</Tip>
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/authentication-details.png" alt="Authentication Details form showing External ID, two deployment buttons (Create Stack in Management Account and Open StackSets Console), Management Account Role ARN field, and deployment confirmation checkbox" />
|
||||
<img src="/images/organizations/authentication-details.png" alt="Authentication Details form showing External ID, Organizational Unit or Root ID field, delegated administrator checkbox, deployment account stack button, deployment account Role ARN field, and deployment confirmation checkbox" />
|
||||
</Frame>
|
||||
|
||||
### Enter the Management Account Role ARN
|
||||
### Enter the Deployment Account Role ARN
|
||||
|
||||
Paste the **Role ARN** of the management account role you created in [Step 1](#step-1-create-the-management-account-role) into the **Management Account Role ARN** field.
|
||||
Paste the **Role ARN** created by the single stack above into the **Management Account Role ARN** field or, when delegated administrator mode is selected, the **Delegated Administrator Account Role ARN** field. If you deployed the management account role beforehand, use the role created in [Step 1](#step-1-create-the-management-account-role).
|
||||
|
||||
The ARN follows this format:
|
||||
```
|
||||
@@ -312,12 +331,12 @@ arn:aws:iam::<account-id>:role/ProwlerScan
|
||||
For example: `arn:aws:iam::123456789012:role/ProwlerScan`
|
||||
|
||||
<Frame>
|
||||
<img src="/images/organizations/role-arn-field.png" alt="Management Account Role ARN field in the Authentication Details form" />
|
||||
<img src="/images/organizations/role-arn-field.png" alt="Deployment account Role ARN field in the Authentication Details form" />
|
||||
</Frame>
|
||||
|
||||
### Confirm and Discover
|
||||
|
||||
1. Check the box: **"The Stack and StackSet have been successfully deployed in AWS"**.
|
||||
1. Check the box: **"The Stack has been successfully deployed in AWS"**.
|
||||
2. Click **Authenticate**.
|
||||
|
||||
Here's what happens behind the scenes:
|
||||
|
||||
Reference in New Issue
Block a user