docs(aws): add AWS Organizations (#10183)

permissions/templates/cloudformation/prowler-scan-role.yml

@@ -36,6 +36,15 @@ Parameters:
       The IAM principal type and name that will be allowed to assume the role created, leave an * for all the IAM principals in your AWS account. If you are deploying this template to be used in Prowler Cloud please do not edit this.
     Type: String
     Default: role/prowler*
+  EnableOrganizations:
+    Description: |
+      Enable AWS Organizations discovery permissions. Set to true only when deploying this role in the management account.
+      This adds read-only Organizations permissions (e.g. ListAccounts, DescribeOrganization) and StackSet management permissions.
+    Type: String
+    Default: false
+    AllowedValues:
+      - true
+      - false
   EnableS3Integration:
     Description: |
       Enable S3 integration for storing Prowler scan reports.
@@ -56,6 +65,7 @@ Parameters:
     Default: ""
 
 Conditions:
+  OrganizationsEnabled: !Equals [!Ref EnableOrganizations, true]
   S3IntegrationEnabled: !Equals [!Ref EnableS3Integration, true]
 
 
@@ -140,6 +150,30 @@ Resources:
                 Resource:
                   - "arn:*:apigateway:*::/restapis/*"
                   - "arn:*:apigateway:*::/apis/*"
+        - !If
+          - OrganizationsEnabled
+          - PolicyName: ProwlerOrganizations
+            PolicyDocument:
+              Version: "2012-10-17"
+              Statement:
+                - Sid: AllowOrganizationsReadOnly
+                  Effect: Allow
+                  Action:
+                    - "organizations:DescribeAccount"
+                    - "organizations:DescribeOrganization"
+                    - "organizations:ListAccounts"
+                    - "organizations:ListAccountsForParent"
+                    - "organizations:ListOrganizationalUnitsForParent"
+                    - "organizations:ListRoots"
+                    - "organizations:ListTagsForResource"
+                  Resource: "*"
+                - Sid: AllowStackSetManagement
+                  Effect: Allow
+                  Action:
+                    - "organizations:RegisterDelegatedAdministrator"
+                    - "iam:CreateServiceLinkedRole"
+                  Resource: "*"
+          - !Ref AWS::NoValue
         - !If
           - S3IntegrationEnabled
           - PolicyName: S3Integration
@@ -191,6 +225,7 @@ Metadata:
           - ExternalId
           - AccountId
           - IAMPrincipal
+          - EnableOrganizations
           - EnableS3Integration
       - Label:
           default: Optional

permissions/templates/terraform/main.tf

@@ -67,6 +67,45 @@ resource "aws_iam_role_policy_attachment" "prowler_scan_viewonly_policy_attachme
   policy_arn = "arn:${data.aws_partition.current.partition}:iam::aws:policy/job-function/ViewOnlyAccess"
 }
 
+# Organizations Policy (management account only)
+###################################
+data "aws_iam_policy_document" "prowler_organizations_policy" {
+  count = var.enable_organizations ? 1 : 0
+
+  statement {
+    sid    = "AllowOrganizationsReadOnly"
+    effect = "Allow"
+    actions = [
+      "organizations:DescribeAccount",
+      "organizations:DescribeOrganization",
+      "organizations:ListAccounts",
+      "organizations:ListAccountsForParent",
+      "organizations:ListOrganizationalUnitsForParent",
+      "organizations:ListRoots",
+      "organizations:ListTagsForResource",
+    ]
+    resources = ["*"]
+  }
+
+  statement {
+    sid    = "AllowStackSetManagement"
+    effect = "Allow"
+    actions = [
+      "organizations:RegisterDelegatedAdministrator",
+      "iam:CreateServiceLinkedRole",
+    ]
+    resources = ["*"]
+  }
+}
+
+resource "aws_iam_role_policy" "prowler_organizations_policy" {
+  count = var.enable_organizations ? 1 : 0
+
+  name   = "ProwlerOrganizations"
+  role   = aws_iam_role.prowler_scan.name
+  policy = data.aws_iam_policy_document.prowler_organizations_policy[0].json
+}
+
 # S3 Integration Module
 ###################################
 module "s3_integration" {

permissions/templates/terraform/variables.tf

@@ -27,6 +27,12 @@ variable "iam_principal" {
   default     = "role/prowler*"
 }
 
+variable "enable_organizations" {
+  type        = bool
+  description = "Enable AWS Organizations discovery permissions. Set to true only when deploying this role in the management account."
+  default     = false
+}
+
 variable "enable_s3_integration" {
   type        = bool
   description = "Enable S3 integration for storing Prowler scan reports."