fix(aws): lead the partition bootstrap regions with the configured region (#12764)

Co-authored-by: pedrooot <pedromarting3@gmail.com>

Author: cesararroba

docs/user-guide/providers/aws/regions-and-partitions.mdx

@@ -21,10 +21,28 @@ When scanning the China (`aws-cn`), European Sovereign Cloud (`aws-eusc`) or Gov
 
 - 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 for more information about the AWS credential configuration.
 
 </Note>
+### Declaring the Partition
+
+`PROWLER_AWS_PARTITION` tells Prowler which partition the scan runs against, without relying on a region being configured:
+
+```bash
+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.
+
+<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.
+</Note>
+
 ### Scanning Specific Regions
 
 To scan a particular AWS region with Prowler, use:

prowler/changelog.d/aws-partition-bootstrap-region-honours-configured-region.fixed.md

@@ -0,0 +1 @@
+Bootstrap STS calls now use the session region when `PROWLER_AWS_PARTITION` is set and the region belongs to that partition, instead of always going to the partition's global STS region, which a deployment reached only through its own region's VPC endpoints cannot route to

prowler/providers/aws/aws_provider.py

@@ -576,8 +576,15 @@ def get_profile_region(
     ) -> str:
         excluded_regions = set(excluded_regions or ())
         session_region = session.region_name
+        env_partition_regions = get_env_partition_regions(session_region)
         if session_region and session_region not in excluded_regions:
-            return session_region
+            if not env_partition_regions or session_region in env_partition_regions:
+                return session_region
+        if env_partition_regions:
+            for region in env_partition_regions:
+                if region not in excluded_regions:
+                    return region
+            return env_partition_regions[0]
 
         for region in AwsProvider.get_bootstrap_region_candidates(session_region):
             if region not in excluded_regions:
@@ -673,7 +680,7 @@ def setup_session(
                 session = Session(**session_arguments)
                 session._session.set_default_client_config(session_config)
                 sts_region = (
-                    get_env_partition_bootstrap_region()
+                    get_env_partition_bootstrap_region(session.region_name)
                     or session.region_name
                     or AWS_STS_GLOBAL_ENDPOINT_REGION
                 )
@@ -1420,12 +1427,6 @@ def test_connection(
             Connection(is_connected=True, Error=None))
         """
         try:
-            if aws_region is None:
-                aws_region = (
-                    get_env_partition_bootstrap_region()
-                    or AWS_STS_GLOBAL_ENDPOINT_REGION
-                )
-
             session = AwsProvider.setup_session(
                 mfa=mfa_enabled,
                 profile=profile,
@@ -1434,6 +1435,12 @@ def test_connection(
                 aws_session_token=aws_session_token,
             )
 
+            if aws_region is None:
+                aws_region = (
+                    get_env_partition_bootstrap_region(session.region_name)
+                    or AWS_STS_GLOBAL_ENDPOINT_REGION
+                )
+
             if role_arn:
                 session_duration = validate_session_duration(session_duration)
                 role_session_name = validate_role_session_name(role_session_name)
@@ -1759,11 +1766,18 @@ def get_botocore_partition_regions() -> dict:
     return partition_regions
 
 
-def get_env_partition_regions() -> Optional[list]:
+def get_env_partition_regions(
+    session_region: Optional[str] = None,
+) -> Optional[list]:
     """
     Get the bootstrap region candidates for the partition set in the
     PROWLER_AWS_PARTITION environment variable.
 
+    Args:
+        session_region (Optional[str]): The region of the AWS session. It leads
+            the candidates when it belongs to the partition and is ignored
+            otherwise.
+
     Returns:
         Optional[list]: The regions of the configured partition, preferred
             bootstrap region first, or None when the environment variable is
@@ -1782,22 +1796,33 @@ def get_env_partition_regions() -> Optional[list]:
         raise AWSInvalidPartitionError(
             message=f"Invalid partition: {raw_partition} set in PROWLER_AWS_PARTITION. Valid partitions: {', '.join(sorted(partition_regions))}"
         )
+
+    # A deployment reached only through its own region's endpoints has no route
+    # to the partition's global STS region, so the session region goes first
+    if session_region in regions:
+        regions = [session_region] + [r for r in regions if r != session_region]
     return regions
 
 
-def get_env_partition_bootstrap_region() -> Optional[str]:
+def get_env_partition_bootstrap_region(
+    session_region: Optional[str] = None,
+) -> Optional[str]:
     """
     Get the STS bootstrap region for the partition set in the
     PROWLER_AWS_PARTITION environment variable.
 
+    Args:
+        session_region (Optional[str]): The region of the AWS session, preferred
+            when it belongs to the partition.
+
     Returns:
         Optional[str]: The preferred bootstrap region of the configured
             partition, or None when the environment variable is not set.
 
     Raises:
         AWSInvalidPartitionError: If the value is not a partition known to botocore.
     """
-    regions = get_env_partition_regions()
+    regions = get_env_partition_regions(session_region)
     return regions[0] if regions else None
 
 
@@ -1833,7 +1858,7 @@ def get_aws_region_for_sts(
             if region not in excluded_regions:
                 return region
 
-    env_partition_regions = get_env_partition_regions()
+    env_partition_regions = get_env_partition_regions(session_region)
     if env_partition_regions:
         # The configured partition constrains the whole fallback chain: prefer
         # a non-excluded region, but never leave the partition