iam-policy-validator 1.7.1__py3-none-any.whl → 1.8.0__py3-none-any.whl

iam_validator/checks/policy_type_validation.py

@@ -30,6 +30,10 @@ async def execute_policy(
     """
     issues = []
 
+    # Handle policies with no statements
+    if not policy.statement:
+        return issues
+
     # Check if any statement has Principal
     has_any_principal = any(
         stmt.principal is not None or stmt.not_principal is not None for stmt in policy.statement
@@ -37,24 +41,36 @@ async def execute_policy(
 
     # If policy has Principal but type is IDENTITY_POLICY (default), provide helpful info
     if has_any_principal and policy_type == "IDENTITY_POLICY":
+        # Check if it's a trust policy
+        from iam_validator.checks.policy_structure import is_trust_policy
+
+        if is_trust_policy(policy):
+            hint_msg = (
+                "Policy contains assume role actions - this is a TRUST POLICY. "
+                "Use --policy-type TRUST_POLICY for proper validation (suppresses missing Resource warnings, "
+                "enables trust-specific validation)"
+            )
+            suggestion_msg = "iam-validator validate --path <file> --policy-type TRUST_POLICY"
+        else:
+            hint_msg = "Policy contains Principal element - this suggests it's a RESOURCE POLICY. Use --policy-type RESOURCE_POLICY"
+            suggestion_msg = "iam-validator validate --path <file> --policy-type RESOURCE_POLICY"
+
         issues.append(
             ValidationIssue(
                 severity="info",
                 issue_type="policy_type_hint",
-                message="Policy contains Principal element - this suggests it's a resource policy. "
-                "Use --policy-type RESOURCE_POLICY for proper validation.",
+                message=hint_msg,
                 statement_index=0,
                 statement_sid=None,
                 line_number=None,
-                suggestion="If this is a resource policy (S3 bucket policy, SNS topic policy, etc.), "
-                "run validation with: iam-validator validate --path <file> --policy-type RESOURCE_POLICY",
+                suggestion=suggestion_msg,
             )
         )
         # Don't run further checks if we're just hinting
         return issues
 
-    # Resource policies MUST have Principal
-    if policy_type == "RESOURCE_POLICY":
+    # Resource policies and Trust policies MUST have Principal
+    if policy_type in ("RESOURCE_POLICY", "TRUST_POLICY"):
         for idx, statement in enumerate(policy.statement):
             has_principal = statement.principal is not None or statement.not_principal is not None
 
@@ -63,13 +79,13 @@ async def execute_policy(
                     ValidationIssue(
                         severity="error",
                         issue_type="missing_principal",
-                        message="Resource policy statement missing required Principal element. "
+                        message="Resource policy statement missing required `Principal` element. "
                         "Resource-based policies (S3 bucket policies, SNS topic policies, etc.) "
-                        "must include a Principal element to specify who can access the resource.",
+                        "must include a `Principal` element to specify who can access the resource.",
                         statement_index=idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion="Add a Principal element to specify who can access this resource.\n"
+                        suggestion="Add a `Principal` element to specify who can access this resource.\n"
                         "Example:\n"
                         "```json\n"
                         "{\n"
@@ -94,14 +110,14 @@ async def execute_policy(
                     ValidationIssue(
                         severity="warning",
                         issue_type="unexpected_principal",
-                        message="Identity policy should not contain Principal element. "
+                        message="Identity policy should not contain `Principal` element. "
                         "Identity-based policies (attached to IAM users, groups, or roles) "
-                        "do not need a Principal element because the principal is implicit "
+                        "do not need a `Principal` element because the principal is implicit "
                         "(the entity the policy is attached to).",
                         statement_index=idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion="Remove the Principal element from this identity policy statement.\n"
+                        suggestion="Remove the `Principal` element from this identity policy statement.\n"
                         "Example:\n"
                         "```json\n"
                         "{\n"
@@ -123,13 +139,13 @@ async def execute_policy(
                     ValidationIssue(
                         severity="error",
                         issue_type="invalid_principal",
-                        message="Service Control Policy must not contain Principal element. "
+                        message="Service Control Policy must not contain `Principal` element. "
                         "Service Control Policies (SCPs) in AWS Organizations do not support "
-                        "the Principal element. They apply to all principals in the organization or OU.",
+                        "the `Principal` element. They apply to all principals in the organization or OU.",
                         statement_index=idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion="Remove the Principal element from this SCP statement.\n"
+                        suggestion="Remove the `Principal` element from this SCP statement.\n"
                         "Example:\n"
                         "```json\n"
                         "{\n"
@@ -177,7 +193,7 @@ async def execute_policy(
                     ValidationIssue(
                         severity="error",
                         issue_type="invalid_rcp_not_principal",
-                        message="Resource Control Policy must not contain NotPrincipal element. "
+                        message="Resource Control Policy must not contain `NotPrincipal` element. "
                         "RCPs only support Principal with value '*'. Use Condition elements "
                         "to restrict specific principals.",
                         statement_index=idx,
@@ -192,13 +208,13 @@ async def execute_policy(
                     ValidationIssue(
                         severity="error",
                         issue_type="missing_rcp_principal",
-                        message="Resource Control Policy statement must have Principal: '*'. "
-                        "RCPs require the Principal element with value '*'. Use Condition "
+                        message="Resource Control Policy statement must have `Principal`: '*'. "
+                        "RCPs require the `Principal` element with value '*'. Use `Condition` "
                         "elements to restrict specific principals.",
                         statement_index=idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion='Add Principal: "*" to this RCP statement.',
+                        suggestion='Add `Principal: "*"` to this RCP statement.',
                     )
                 )
             elif statement.principal != "*":
@@ -209,13 +225,13 @@ async def execute_policy(
                         ValidationIssue(
                             severity="error",
                             issue_type="invalid_rcp_principal",
-                            message="Resource Control Policy Principal must be '*'. "
-                            f"Found: {statement.principal}. RCPs can only specify '*' in the "
-                            "Principal element. Use Condition elements to restrict specific principals.",
+                            message=f'Resource Control Policy `Principal` must be `"*"`. '
+                            f'Found: `{statement.principal}`. RCPs can only specify `"*"` in the '
+                            "`Principal` element. Use `Condition` elements to restrict specific principals.",
                             statement_index=idx,
                             statement_sid=statement.sid,
                             line_number=statement.line_number,
-                            suggestion='Change Principal to "*" and use Condition elements to restrict access.',
+                            suggestion='Change `Principal` to `"*"` and use `Condition` elements to restrict access.',
                         )
                     )
 
@@ -234,13 +250,13 @@ async def execute_policy(
                                 ValidationIssue(
                                     severity="error",
                                     issue_type="invalid_rcp_wildcard_action",
-                                    message="Resource Control Policy must not use '*' alone in Action element. "
-                                    "Customer-managed RCPs cannot use '*' as the action wildcard. "
-                                    "Use service-specific wildcards like 's3:*' instead.",
+                                    message="Resource Control Policy must not use `*` alone in `Action` element. "
+                                    "Customer-managed RCPs cannot use `*` as the action wildcard. "
+                                    "Use service-specific wildcards like `s3:*` instead.",
                                     statement_index=idx,
                                     statement_sid=statement.sid,
                                     line_number=statement.line_number,
-                                    suggestion="Replace '*' with service-specific actions from supported "
+                                    suggestion="Replace `*` with service-specific actions from supported "
                                     f"services: {', '.join(sorted(rcp_supported_services))}",
                                 )
                             )
@@ -275,12 +291,12 @@ async def execute_policy(
                     ValidationIssue(
                         severity="error",
                         issue_type="invalid_rcp_not_action",
-                        message="Resource Control Policy must not contain NotAction element. "
-                        "RCPs do not support NotAction. Use Action element instead.",
+                        message="Resource Control Policy must not contain `NotAction` element. "
+                        "RCPs do not support `NotAction`. Use `Action` element instead.",
                         statement_index=idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion="Replace NotAction with Action element listing the specific "
+                        suggestion="Replace `NotAction` with `Action` element listing the specific "
                         "actions to deny.",
                     )
                 )
@@ -294,11 +310,11 @@ async def execute_policy(
                     ValidationIssue(
                         severity="error",
                         issue_type="missing_rcp_resource",
-                        message="Resource Control Policy statement must have Resource or NotResource element.",
+                        message="Resource Control Policy statement must have `Resource` or `NotResource` element.",
                         statement_index=idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion='Add Resource: "*" or specify specific resource ARNs.',
+                        suggestion='Add `Resource: "*"` or specify specific resource ARNs.',
                     )
                 )
 

iam_validator/checks/principal_validation.py

@@ -4,36 +4,34 @@ Validates Principal elements in resource-based policies for security best practi
 This check enforces:
 - Blocked principals (e.g., public access via "*")
 - Allowed principals whitelist (optional)
-- Required conditions for specific principals (simple format)
-- Rich condition requirements for principals (advanced format with all_of/any_of)
+- Rich condition requirements for principals (supports any_of/all_of/none_of)
 - Service principal validation
 
-Only runs for RESOURCE_POLICY type policies.
-
-Configuration supports TWO formats:
-
-1. Simple format (backward compatible):
-   require_conditions_for:
-     "*": ["aws:SourceArn", "aws:SourceAccount"]
-     "arn:aws:iam::*:root": ["aws:PrincipalOrgID"]
-
-2. Advanced format with rich condition requirements:
-   principal_condition_requirements:
-     - principals:
-         - "*"
-       severity: critical
-       required_conditions:
-         all_of:
-           - condition_key: "aws:SourceArn"
-             description: "Limit by source ARN"
-           - condition_key: "aws:SourceAccount"
-
-     - principals:
-         - "arn:aws:iam::*:root"
-       required_conditions:
-         - condition_key: "aws:PrincipalOrgID"
-           expected_value: "o-xxxxx"
-           operator: "StringEquals"
+Only runs for RESOURCE_POLICY and TRUST_POLICY types.
+
+Configuration format:
+
+principal_condition_requirements:
+  - principals:
+      - "*"  # Can be a list of principal patterns
+    severity: critical  # Optional: override default severity
+    required_conditions:
+      any_of:  # At least ONE of these conditions must be present
+        - condition_key: "aws:SourceArn"
+          description: "Limit by source ARN"
+        - condition_key: "aws:SourceAccount"
+          expected_value: "123456789012"  # Optional: validate specific value
+          operator: "StringEquals"  # Optional: validate specific operator
+
+  - principals:
+      - "arn:aws:iam::*:root"
+    required_conditions:
+      all_of:  # ALL of these conditions must be present
+        - condition_key: "aws:PrincipalOrgID"
+          expected_value: "o-xxxxx"
+        - condition_key: "aws:SourceAccount"
+
+Supports: any_of, all_of, none_of, and expected_value (single value or list)
 """
 
 import fnmatch
@@ -41,6 +39,7 @@ from typing import Any
 
 from iam_validator.core.aws_fetcher import AWSServiceFetcher
 from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.config.service_principals import is_aws_service_principal
 from iam_validator.core.models import Statement, ValidationIssue
 
 
@@ -83,22 +82,13 @@ class PrincipalValidationCheck(PolicyCheck):
         if statement.principal is None and statement.not_principal is None:
             return issues
 
-        # Get configuration
+        # Get configuration (defaults match defaults.py)
         blocked_principals = config.config.get("blocked_principals", ["*"])
         allowed_principals = config.config.get("allowed_principals", [])
-        require_conditions_for = config.config.get("require_conditions_for", {})
         principal_condition_requirements = config.config.get("principal_condition_requirements", [])
-        allowed_service_principals = config.config.get(
-            "allowed_service_principals",
-            [
-                "cloudfront.amazonaws.com",
-                "s3.amazonaws.com",
-                "sns.amazonaws.com",
-                "lambda.amazonaws.com",
-                "logs.amazonaws.com",
-                "events.amazonaws.com",
-            ],
-        )
+        # Default: "aws:*" allows ALL AWS service principals (*.amazonaws.com)
+        # This matches the default in defaults.py:251
+        allowed_service_principals = config.config.get("allowed_service_principals", ["aws:*"])
 
         # Extract principals from statement
         principals = self._extract_principals(statement)
@@ -112,13 +102,13 @@ class PrincipalValidationCheck(PolicyCheck):
                     ValidationIssue(
                         severity=self.get_severity(config),
                         issue_type="blocked_principal",
-                        message=f"Blocked principal detected: {principal}. "
+                        message=f"Blocked principal detected: `{principal}`. "
                         f"This principal is explicitly blocked by your security policy.",
                         statement_index=statement_idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion=f"Remove the principal '{principal}' or add appropriate conditions to restrict access. "
-                        "Consider using more specific principals instead of wildcards.",
+                        suggestion=f"Remove the `Principal` `{principal}` or add appropriate `Condition`s to restrict access. "
+                        "Consider using more specific `Principal`s instead of `*` (wildcard).",
                     )
                 )
                 continue
@@ -131,45 +121,25 @@ class PrincipalValidationCheck(PolicyCheck):
                     ValidationIssue(
                         severity=self.get_severity(config),
                         issue_type="unauthorized_principal",
-                        message=f"Principal not in allowed list: {principal}. "
-                        f"Only principals in the allowed_principals whitelist are permitted.",
+                        message=f"`Principal` not in allowed list: `{principal}`. "
+                        f"Only principals in the `allowed_principals` whitelist are permitted.",
                         statement_index=statement_idx,
                         statement_sid=statement.sid,
                         line_number=statement.line_number,
-                        suggestion=f"Add '{principal}' to the allowed_principals list in your config, "
-                        "or use a principal that matches an allowed pattern.",
+                        suggestion=f"Add `{principal}` to the `allowed_principals` list in your config, "
+                        "or use a `Principal` that matches an allowed pattern.",
                     )
                 )
                 continue
 
-            # Check simple format: require_conditions_for (backward compatible)
-            required_conditions = self._get_required_conditions(principal, require_conditions_for)
-            if required_conditions:
-                missing_conditions = self._check_required_conditions(statement, required_conditions)
-                if missing_conditions:
-                    issues.append(
-                        ValidationIssue(
-                            severity=self.get_severity(config),
-                            issue_type="missing_principal_conditions",
-                            message=f"Principal '{principal}' requires conditions: {', '.join(missing_conditions)}. "
-                            f"This principal must have these condition keys to restrict access.",
-                            statement_index=statement_idx,
-                            statement_sid=statement.sid,
-                            line_number=statement.line_number,
-                            suggestion=f"Add conditions to restrict access:\n"
-                            f"Example:\n"
-                            f'"Condition": {{\n'
-                            f'  "StringEquals": {{\n'
-                            f'    "{missing_conditions[0]}": "value"\n'
-                            f"  }}\n"
-                            f"}}",
-                        )
-                    )
-
-        # Check advanced format: principal_condition_requirements
+        # Check principal_condition_requirements (supports any_of/all_of/none_of)
         if principal_condition_requirements:
             condition_issues = self._validate_principal_condition_requirements(
-                statement, statement_idx, principals, principal_condition_requirements, config
+                statement,
+                statement_idx,
+                principals,
+                principal_condition_requirements,
+                config,
             )
             issues.extend(condition_issues)
 
@@ -193,7 +163,7 @@ class PrincipalValidationCheck(PolicyCheck):
                 principals.append(statement.principal)
             elif isinstance(statement.principal, dict):
                 # Dict with AWS, Service, Federated, etc.
-                for key, value in statement.principal.items():
+                for _, value in statement.principal.items():
                     if isinstance(value, str):
                         principals.append(value)
                     elif isinstance(value, list):
@@ -204,7 +174,7 @@ class PrincipalValidationCheck(PolicyCheck):
             if isinstance(statement.not_principal, str):
                 principals.append(statement.not_principal)
             elif isinstance(statement.not_principal, dict):
-                for key, value in statement.not_principal.items():
+                for _, value in statement.not_principal.items():
                     if isinstance(value, str):
                         principals.append(value)
                     elif isinstance(value, list):
@@ -220,13 +190,17 @@ class PrincipalValidationCheck(PolicyCheck):
         Args:
             principal: The principal to check
             blocked_list: List of blocked principal patterns
-            service_whitelist: List of allowed service principals
+            service_whitelist: List of allowed service principals (supports "aws:*" for all AWS services)
 
         Returns:
             True if the principal is blocked
         """
-        # Service principals are never blocked
-        if principal in service_whitelist:
+        # Check if service_whitelist contains "aws:*" (allow all AWS service principals)
+        if "aws:*" in service_whitelist and is_aws_service_principal(principal):
+            return False
+
+        # Service principals in explicit whitelist are never blocked
+        if is_aws_service_principal(principal) and principal in service_whitelist:
             return False
 
         # Check against blocked list (supports wildcards)
@@ -249,13 +223,17 @@ class PrincipalValidationCheck(PolicyCheck):
         Args:
             principal: The principal to check
             allowed_list: List of allowed principal patterns
-            service_whitelist: List of allowed service principals
+            service_whitelist: List of allowed service principals (supports "aws:*" for all AWS services)
 
         Returns:
             True if the principal is allowed
         """
-        # Service principals are always allowed
-        if principal in service_whitelist:
+        # Check if service_whitelist contains "aws:*" (allow all AWS service principals)
+        if "aws:*" in service_whitelist and is_aws_service_principal(principal):
+            return True
+
+        # Service principals in explicit whitelist are always allowed
+        if is_aws_service_principal(principal) and principal in service_whitelist:
             return True
 
         # Check against allowed list (supports wildcards)
@@ -270,52 +248,6 @@ class PrincipalValidationCheck(PolicyCheck):
 
         return False
 
-    def _get_required_conditions(
-        self, principal: str, requirements: dict[str, list[str]]
-    ) -> list[str]:
-        """Get required condition keys for a principal.
-
-        Args:
-            principal: The principal to check
-            requirements: Dict mapping principal patterns to required condition keys
-
-        Returns:
-            List of required condition keys
-        """
-        for pattern, condition_keys in requirements.items():
-            # Special case: "*" pattern should only match literal "*" (public access)
-            if pattern == "*":
-                if principal == "*":
-                    return condition_keys
-            elif fnmatch.fnmatch(principal, pattern):
-                return condition_keys
-        return []
-
-    def _check_required_conditions(
-        self, statement: Statement, required_keys: list[str]
-    ) -> list[str]:
-        """Check if statement has required condition keys.
-
-        Args:
-            statement: The statement to check
-            required_keys: List of required condition keys
-
-        Returns:
-            List of missing condition keys
-        """
-        if not statement.condition:
-            return required_keys
-
-        # Flatten all condition keys from all condition operators
-        present_keys = set()
-        for operator_conditions in statement.condition.values():
-            if isinstance(operator_conditions, dict):
-                present_keys.update(operator_conditions.keys())
-
-        # Find missing keys
-        missing = [key for key in required_keys if key not in present_keys]
-        return missing
-
     def _validate_principal_condition_requirements(
         self,
         statement: Statement,
@@ -469,6 +401,7 @@ class PrincipalValidationCheck(PolicyCheck):
                     # Create a combined error for any_of
                     condition_keys = [cond.get("condition_key", "unknown") for cond in any_of]
                     severity = requirement.get("severity", self.get_severity(config))
+                    matching_principals_str = ", ".join(f"`{p}`" for p in matching_principals)
                     issues.append(
                         ValidationIssue(
                             severity=severity,
@@ -476,8 +409,8 @@ class PrincipalValidationCheck(PolicyCheck):
                             statement_index=statement_idx,
                             issue_type="missing_principal_condition_any_of",
                             message=(
-                                f"Principals {matching_principals} require at least ONE of these conditions: "
-                                f"{', '.join(condition_keys)}"
+                                f"`Principal`s `{matching_principals_str}` require at least ONE of these conditions: "
+                                f"{', '.join(f'`{c}`' for c in condition_keys)}"
                             ),
                             suggestion=self._build_any_of_suggestion(any_of),
                             line_number=statement.line_number,
@@ -629,15 +562,20 @@ class PrincipalValidationCheck(PolicyCheck):
             or self.get_severity(config)
         )
 
+        suggestion_text, example_code = self._build_condition_suggestion(
+            condition_key, description, example, expected_value, operator
+        )
+
+        matching_principals_formatted = ", ".join(f"`{p}`" for p in matching_principals)
+
         return ValidationIssue(
             severity=severity,
             statement_sid=statement.sid,
             statement_index=statement_idx,
             issue_type="missing_principal_condition",
-            message=f"{message_prefix} Principal(s) {matching_principals} require condition '{condition_key}'",
-            suggestion=self._build_condition_suggestion(
-                condition_key, description, example, expected_value, operator
-            ),
+            message=f"{message_prefix} Principal(s) {matching_principals_formatted} require condition `{condition_key}`",
+            suggestion=suggestion_text,
+            example=example_code,
             line_number=statement.line_number,
         )
 
@@ -648,8 +586,8 @@ class PrincipalValidationCheck(PolicyCheck):
         example: str,
         expected_value: Any = None,
         operator: str = "StringEquals",
-    ) -> str:
-        """Build a helpful suggestion for adding the missing condition.
+    ) -> tuple[str, str]:
+        """Build suggestion and example for adding the missing condition.
 
         Args:
             condition_key: The condition key
@@ -659,19 +597,16 @@ class PrincipalValidationCheck(PolicyCheck):
             operator: Condition operator
 
         Returns:
-            Suggestion string
+            Tuple of (suggestion_text, example_code)
         """
-        parts = []
-
-        if description:
-            parts.append(description)
+        suggestion = description if description else f"Add condition: {condition_key}"
 
         # Build example based on condition key type
         if example:
-            parts.append(f"Example:\n```json\n{example}\n```")
+            example_code = example
         else:
             # Auto-generate example
-            example_lines = ['Add to "Condition" block:', f'  "{operator}": {{']
+            example_lines = [f'  "{operator}": {{']
 
             if isinstance(expected_value, list):
                 value_str = (
@@ -698,9 +633,9 @@ class PrincipalValidationCheck(PolicyCheck):
             example_lines.append(f'    "{condition_key}": {value_str}')
             example_lines.append("  }")
 
-            parts.append("\n".join(example_lines))
+            example_code = "\n".join(example_lines)
 
-        return ". ".join(parts) if parts else f"Add condition: {condition_key}"
+        return suggestion, example_code
 
     def _build_any_of_suggestion(self, any_of_conditions: list[dict[str, Any]]) -> str:
         """Build suggestion for any_of conditions.
@@ -719,11 +654,11 @@ class PrincipalValidationCheck(PolicyCheck):
             description = cond.get("description", "")
             expected_value = cond.get("expected_value")
 
-            option = f"\nOption {i}: {condition_key}"
+            option = f"\n- **Option {i}**: `{condition_key}`"
             if description:
                 option += f" - {description}"
             if expected_value is not None:
-                option += f" (value: {expected_value})"
+                option += f" (value: `{expected_value}`)"
 
             suggestions.append(option)
 
@@ -755,11 +690,12 @@ class PrincipalValidationCheck(PolicyCheck):
         description = condition_requirement.get("description", "")
         expected_value = condition_requirement.get("expected_value")
 
-        message = f"FORBIDDEN: Principal(s) {matching_principals} must NOT have condition '{condition_key}'"
+        matching_principals_str = ", ".join(f"`{p}`" for p in matching_principals)
+        message = f"FORBIDDEN: `Principal`s `{matching_principals_str}` must NOT have `Condition` `{condition_key}`"
         if expected_value is not None:
-            message += f" with value '{expected_value}'"
+            message += f" with value `{expected_value}`"
 
-        suggestion = f"Remove the '{condition_key}' condition from the statement"
+        suggestion = f"Remove the `{condition_key}` `Condition` from the statement"
         if description:
             suggestion += f". {description}"
 

iam_validator/checks/resource_validation.py

@@ -75,7 +75,7 @@ class ResourceValidationCheck(PolicyCheck):
                         issue_type="invalid_resource",
                         message=f"Resource ARN exceeds maximum length ({len(resource)} > {MAX_ARN_LENGTH}): {resource[:100]}...",
                         resource=resource[:100] + "...",
-                        suggestion="ARN is too long and may be invalid",
+                        suggestion="`ARN` is too long and may be invalid",
                         line_number=line_number,
                     )
                 )
@@ -101,9 +101,9 @@ class ResourceValidationCheck(PolicyCheck):
                                 statement_sid=statement_sid,
                                 statement_index=statement_idx,
                                 issue_type="invalid_resource",
-                                message=f"Invalid ARN format even after normalizing template variables: {resource}",
+                                message=f"Invalid `ARN` format even after normalizing template variables: `{resource}`",
                                 resource=resource,
-                                suggestion="ARN should follow format: arn:partition:service:region:account-id:resource (template variables like ${aws_account_id} are supported)",
+                                suggestion="`ARN` should follow format: `arn:partition:service:region:account-id:resource` (template variables like `${aws_account_id}` are supported)",
                                 line_number=line_number,
                             )
                         )
@@ -114,13 +114,13 @@ class ResourceValidationCheck(PolicyCheck):
                                 statement_sid=statement_sid,
                                 statement_index=statement_idx,
                                 issue_type="invalid_resource",
-                                message=f"Invalid ARN format: {resource}",
+                                message=f"Invalid `ARN` format: `{resource}`",
                                 resource=resource,
-                                suggestion="ARN should follow format: arn:partition:service:region:account-id:resource",
+                                suggestion="`ARN` should follow format: `arn:partition:service:region:account-id:resource`",
                                 line_number=line_number,
                             )
                         )
-            except Exception:
+            except Exception:  # pylint: disable=broad-exception-caught
                 # If regex matching fails (shouldn't happen with length check), treat as invalid
                 issues.append(
                     ValidationIssue(
@@ -128,9 +128,9 @@ class ResourceValidationCheck(PolicyCheck):
                         statement_sid=statement_sid,
                         statement_index=statement_idx,
                         issue_type="invalid_resource",
-                        message=f"Could not validate ARN format: {resource}",
+                        message=f"Could not validate `ARN` format: `{resource}`",
                         resource=resource,
-                        suggestion="ARN validation failed - may contain unexpected characters",
+                        suggestion="`ARN` validation failed - may contain unexpected characters",
                         line_number=line_number,
                     )
                 )