iam-policy-validator 1.14.6__py3-none-any.whl → 1.15.0__py3-none-any.whl

iam_validator/core/config/aws_global_conditions.py

@@ -71,6 +71,19 @@ AWS_GLOBAL_CONDITION_KEYS = {
     "aws:ViaAWSService": "Bool",  # Whether AWS service made the request
 }
 
+# Global condition keys that restrict resource scope.
+# These conditions are always valid for all services and directly constrain
+# which resources can be accessed, making them suitable for lowering severity
+# when used with wildcard resources.
+# Reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourceaccount
+GLOBAL_RESOURCE_SCOPING_CONDITION_KEYS = frozenset(
+    {
+        "aws:ResourceAccount",  # Limits to specific AWS account(s)
+        "aws:ResourceOrgID",  # Limits to specific AWS Organization
+        "aws:ResourceOrgPaths",  # Limits to specific OU paths
+    }
+)
+
 # Patterns that should be recognized (wildcards and tag-based keys)
 # These allow things like aws:RequestTag/Department or aws:PrincipalTag/Environment
 # Uses centralized tag key character class from constants

iam_validator/core/config/check_documentation.py

@@ -9,6 +9,18 @@ Used to enhance ValidationIssue objects with actionable guidance.
 from dataclasses import dataclass, field
 from typing import ClassVar
 
+# Risk category icons for display in PR comments
+RISK_CATEGORY_ICONS = {
+    "privilege_escalation": "🔐",
+    "data_exfiltration": "📤",
+    "denial_of_service": "🚫",
+    "resource_exposure": "🌐",
+    "credential_exposure": "🔑",
+    "compliance": "📋",
+    "configuration": "⚙️",
+    "validation": "✅",
+}
+
 
 @dataclass
 class CheckDocumentation:
@@ -19,12 +31,14 @@ class CheckDocumentation:
         risk_explanation: Why this issue is a security risk
         documentation_url: Link to relevant AWS docs or runbook
         remediation_steps: Step-by-step fix guidance
+        risk_category: Category of risk (e.g., "privilege_escalation", "data_exfiltration")
     """
 
     check_id: str
     risk_explanation: str
     documentation_url: str
     remediation_steps: list[str] = field(default_factory=list)
+    risk_category: str | None = None
 
 
 class CheckDocumentationRegistry:
@@ -80,15 +94,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="action_validation",
         risk_explanation=(
-            "Invalid actions may silently fail to grant intended permissions, "
+            "Invalid `Action`s may silently fail to grant intended permissions, "
             "or indicate a typo that could expose unintended access."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_REFERENCE}/reference_policies_actions-resources-contextkeys.html",
         remediation_steps=[
-            "Verify the action name against AWS documentation for the target service",
-            "Use the IAM policy simulator to test your intended permissions",
-            "Check for common typos (e.g., 'S3' vs 's3', 'GetObjects' vs 'GetObject')",
+            "Verify the `Action` name against AWS documentation for the target service",
+            "Use the AWS IAM policy simulator to test your intended permissions",
+            "Check for common typos (e.g., `S3` vs `s3`, `GetObjects` vs `GetObject`)",
         ],
+        risk_category="validation",
     )
 )
 
@@ -96,15 +111,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="condition_key_validation",
         risk_explanation=(
-            "Invalid condition keys are silently ignored by IAM, meaning your "
+            "Invalid condition keys are silently ignored by AWS IAM, meaning your "
             "intended access restrictions may not be enforced."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_condition-keys.html",
         remediation_steps=[
-            "Verify the condition key exists for the target service",
-            "Check AWS documentation for the correct key name and format",
-            "Use global condition keys (aws:*) for cross-service restrictions",
+            "Verify the `Condition` key exists for the target service",
+            "Check AWS documentation for the correct `Condition` key name and format for the target service",
+            "Use global condition keys (`aws:*`) for cross-service restrictions",
         ],
+        risk_category="validation",
     )
 )
 
@@ -112,15 +128,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="condition_type_mismatch",
         risk_explanation=(
-            "Using the wrong condition operator type (e.g., StringEquals with a "
+            "Using the wrong condition operator type (e.g., `StringEquals` with a "
             "numeric value) may cause unexpected behavior or silent failures."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_elements_condition_operators.html",
         remediation_steps=[
-            "Match the condition operator to the key's data type",
-            "Use String operators for string keys, Numeric for numbers, Date for timestamps",
-            "Consider using IfExists variants for optional conditions",
+            "Match the condition operator to the `Condition` key's data type",
+            "Use `String` operators for string keys, `Numeric` for numbers, `Date` for timestamps",
+            "Consider using `IfExists` variants for optional conditions",
         ],
+        risk_category="validation",
     )
 )
 
@@ -128,15 +145,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="resource_validation",
         risk_explanation=(
-            "Invalid resource ARNs may silently fail to match intended resources, "
+            "Invalid `Resource` ARNs may silently fail to match intended resources, "
             "leaving permissions ineffective or overly broad."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_REFERENCE}/reference_policies_actions-resources-contextkeys.html",
         remediation_steps=[
-            "Verify ARN format matches the target service's documentation",
+            "Verify `Resource` ARN format matches the target service's documentation",
             "Ensure region and account ID are correct or use wildcards intentionally",
-            "Test the policy with IAM policy simulator before deployment",
+            "Test the policy with AWS IAM policy simulator before deployment",
         ],
+        risk_category="validation",
     )
 )
 
@@ -153,6 +171,7 @@ CheckDocumentationRegistry.register(
             "Use descriptive SIDs that indicate the statement's purpose",
             "Consider a naming convention like 'AllowS3ReadAccess' or 'DenyPublicAccess'",
         ],
+        risk_category="compliance",
     )
 )
 
@@ -161,15 +180,16 @@ CheckDocumentationRegistry.register(
         check_id="policy_size",
         risk_explanation=(
             "Policies exceeding AWS size limits cannot be attached to IAM entities. "
-            "Inline policies have a 2KB limit, managed policies have a 6KB limit."
+            "Inline policies have a 2KB limit, managed policies have a 6KB limit (for the entire policy document)."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_iam-quotas.html",
         remediation_steps=[
             "Split large policies into multiple smaller policies",
             "Use managed policies instead of inline policies for larger permissions",
-            "Remove redundant statements or consolidate similar actions",
+            "Remove redundant statements or consolidate similar `Action`s",
             "Consider using permission boundaries or SCPs for broad restrictions",
         ],
+        risk_category="validation",
     )
 )
 
@@ -177,15 +197,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="policy_structure",
         risk_explanation=(
-            "Malformed policy structure will cause IAM to reject the policy entirely, "
+            "Malformed policy structure will cause AWS IAM to reject the policy entirely, "
             "preventing any permissions from being granted."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_grammar.html",
         remediation_steps=[
             "Verify the policy follows AWS IAM policy grammar",
-            "Ensure all required elements (Version, Statement) are present",
-            "Check that Effect, Action, and Resource are properly formatted",
+            "Ensure all required elements (`Version`, `Statement`) are present",
+            "Check that `Effect`, `Action`, and `Resource` are properly formatted",
         ],
+        risk_category="validation",
     )
 )
 
@@ -193,15 +214,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="set_operator_validation",
         risk_explanation=(
-            "Invalid ForAllValues/ForAnyValue operators may cause conditions to "
+            "Invalid `ForAllValues`/`ForAnyValue` operators may cause conditions to "
             "behave unexpectedly, potentially granting or denying unintended access."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_multi-value-conditions.html",
         remediation_steps=[
-            "Use ForAllValues when ALL values must match the condition",
-            "Use ForAnyValue when ANY value matching is sufficient",
-            "Consider the empty set behavior: ForAllValues returns true for empty sets",
+            "Use `ForAllValues` when ALL values must match the condition",
+            "Use `ForAnyValue` when ANY value matching is sufficient",
+            "Consider the empty set behavior: `ForAllValues` returns true for empty sets",
         ],
+        risk_category="validation",
     )
 )
 
@@ -214,10 +236,11 @@ CheckDocumentationRegistry.register(
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/id_credentials_mfa_configure-api-require.html",
         remediation_steps=[
-            "Add 'aws:MultiFactorAuthPresent': 'true' condition for sensitive actions",
-            "Consider using 'aws:MultiFactorAuthAge' to require recent MFA",
+            "Add `aws:MultiFactorAuthPresent`: `true` condition for sensitive actions",
+            "Consider using `aws:MultiFactorAuthAge` to require recent MFA",
             "Ensure MFA is enforced at the identity level as well as policy level",
         ],
+        risk_category="credential_exposure",
     )
 )
 
@@ -234,6 +257,7 @@ CheckDocumentationRegistry.register(
             "Use specific principals instead of wildcards where possible",
             "For service principals, use the canonical format (e.g., 's3.amazonaws.com')",
         ],
+        risk_category="resource_exposure",
     )
 )
 
@@ -246,10 +270,11 @@ CheckDocumentationRegistry.register(
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/access_policies.html",
         remediation_steps=[
-            "Identity policies: Don't include Principal element",
-            "Resource policies: Include Principal element",
-            "SCPs: Use only Allow statements with specific conditions",
+            "Identity policies: Don't include `Principal` element",
+            "Resource policies: Include `Principal` element",
+            "SCPs: Use only `Allow` statements with specific conditions",
         ],
+        risk_category="configuration",
     )
 )
 
@@ -257,15 +282,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="action_resource_matching",
         risk_explanation=(
-            "Actions that don't support the specified resources will silently fail, "
+            "`Action`s that don't support the specified `Resource`s will silently fail, "
             "resulting in permissions that don't work as intended."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_REFERENCE}/reference_policies_actions-resources-contextkeys.html",
         remediation_steps=[
             "Check AWS documentation for supported resource types per action",
-            "Use '*' for actions that don't support resource-level permissions",
+            "Use `*` (wildcard) for actions that don't support resource-level permissions",
             "Split statements when actions require different resource types",
         ],
+        risk_category="validation",
     )
 )
 
@@ -278,11 +304,12 @@ CheckDocumentationRegistry.register(
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/id_roles_create_for-user.html",
         remediation_steps=[
-            "Restrict Principal to specific accounts/roles/users",
+            "Restrict `Principal` to specific accounts/roles/users (e.g., `arn:aws:iam::123456789012:role/foo`)",
             "Add conditions to limit who can assume the role",
-            "Avoid wildcards in Principal unless absolutely necessary",
+            "Avoid wildcards in `Principal` unless absolutely necessary",
             "Use ExternalId for cross-account role assumption",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -293,16 +320,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="wildcard_action",
         risk_explanation=(
-            "Wildcard actions (e.g., 's3:*') grant all current AND future permissions "
+            "Wildcard actions (e.g., `s3:*`) grant all current AND future permissions "
             "for a service, violating least privilege and increasing attack surface."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
-            "Replace wildcards with specific actions needed for the use case",
-            "Use action groups like 's3:Get*' for read-only access",
-            "Document why each action is required",
-            "Review and reduce permissions periodically",
+            "Replace wildcards with specific `Action` lists needed for the use case",
+            "Use action groups like `s3:Get*` for read-only access",
+            "Review and reduce permissions periodically if not needed",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -310,15 +337,17 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="wildcard_resource",
         risk_explanation=(
-            "Wildcard resources ('*') grant access to ALL resources of a type, "
+            "Wildcard resources (`*`) grant access to ALL resources of a type, "
             "including resources created in the future, violating least privilege."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
-            "Specify exact resource ARNs when possible",
-            "Use resource tags and conditions for dynamic access control",
+            "Specify exact `Resource` ARNs when possible",
+            "Use resource tags and conditions for dynamic access control (ABAC)",
             "Limit scope to specific accounts, regions, or resource prefixes",
+            "Use `aws:ResourceAccount`, `aws:ResourceOrgID`, or `aws:ResourceOrgPaths` conditions to restrict scope",
         ],
+        risk_category="resource_exposure",
     )
 )
 
@@ -336,6 +365,7 @@ CheckDocumentationRegistry.register(
             "Implement permission boundaries to limit maximum possible permissions",
             "Consider using service control policies (SCPs) as guardrails",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -343,15 +373,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="service_wildcard",
         risk_explanation=(
-            "Service-level wildcards (e.g., 'iam:*') grant all permissions for "
+            "Service-level wildcards (e.g., `iam:*`) grant all permissions for "
             "an entire service, including destructive and privilege escalation actions."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
             "Replace with specific actions required for the use case",
             "Use AWS managed policies for common patterns",
-            "Consider permission boundaries to limit sensitive actions",
+            "Consider permission boundaries to limit sensitive actions and enforce least privilege",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -359,16 +390,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="sensitive_action",
         risk_explanation=(
-            "Sensitive actions (e.g., iam:*, sts:AssumeRole, kms:Decrypt) can lead "
+            "Sensitive actions (e.g., `iam:*`, `sts:AssumeRole`, `kms:Decrypt`) can lead "
             "to privilege escalation, data exfiltration, or account compromise."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
             "Add conditions to restrict when these actions can be used",
-            "Require MFA for sensitive operations",
-            "Limit to specific resources where possible",
-            "Implement monitoring and alerting for sensitive action usage",
+            "Require Attribute Based Access Control (ABAC) for sensitive operations",
+            "Limit to specific resources and accounts where possible",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -377,14 +408,36 @@ CheckDocumentationRegistry.register(
         check_id="action_condition_enforcement",
         risk_explanation=(
             "Certain sensitive actions should always have conditions to prevent "
-            "misuse, such as IP restrictions, MFA requirements, or time-based access."
+            "misuse, such as Account/Organization boundaries, VPC/VPCe restrictions, MFA requirements, or time-based access."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_elements_condition.html",
         remediation_steps=[
             "Add appropriate conditions based on the action type",
-            "Use aws:SourceIp for network-restricted actions",
-            "Use aws:MultiFactorAuthPresent for authentication-sensitive actions",
-            "Use aws:RequestedRegion to limit geographic scope",
+            "Use `aws:ResourceAccount` and `aws:PrincipalAccount` for account-restricted actions",
+            "Use `aws:ResourceOrgID` and `aws:PrincipalOrgID` for organization-restricted actions",
+            "Use `aws:SourceVpc` or `aws:SourceVpce` for VPC-restricted actions",
+            "Use `aws:SourceIp` for network-restricted actions",
+            "Use `aws:RequestedRegion` to limit geographic scope",
+        ],
+        risk_category="compliance",
+    )
+)
+
+CheckDocumentationRegistry.register(
+    CheckDocumentation(
+        check_id="not_action_not_resource",
+        risk_explanation=(
+            "`NotAction` and `NotResource` grant permissions by exclusion rather than "
+            "inclusion. This can accidentally grant far more access than intended, "
+            "including access to actions and resources created in the future."
+        ),
+        documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_elements_notaction.html",
+        remediation_steps=[
+            "Replace `NotAction` with explicit `Action` lists when possible",
+            "Replace `NotResource` with specific `Resource` ARNs",
+            "If `NotAction` is required, add strict conditions (`aws:SourceIp`, `aws:SourceVpc`, `aws:SourceVpce`, `aws:ResourceAccount`, `aws:ResourceOrgID`, `aws:RequestedRegion`, etc.)",
+            "Document why exclusion-based permissions are necessary",
         ],
+        risk_category="privilege_escalation",
     )
 )

iam_validator/core/config/config_loader.py

@@ -47,6 +47,7 @@ KNOWN_CHECK_IDS = frozenset(
         "service_wildcard",
         "sensitive_action",
         "action_condition_enforcement",
+        "not_action_not_resource",
     ]
 )
 
@@ -82,6 +83,7 @@ class CheckConfigSchema(BaseModel):
     severity: str | None = None
     description: str | None = None
     ignore_patterns: list[dict[str, Any]] = []
+    hide_severities: list[str] | None = None  # Per-check severity filtering
 
     @field_validator("severity")
     @classmethod
@@ -90,6 +92,18 @@ class CheckConfigSchema(BaseModel):
             raise ValueError(f"Invalid severity: {v}. Must be one of: {sorted(SEVERITY_LEVELS)}")
         return v
 
+    @field_validator("hide_severities")
+    @classmethod
+    def validate_hide_severities(cls, v: list[str] | None) -> list[str] | None:
+        if v is not None:
+            for severity in v:
+                if severity not in SEVERITY_LEVELS:
+                    raise ValueError(
+                        f"Invalid severity in hide_severities: {severity}. "
+                        f"Must be one of: {sorted(SEVERITY_LEVELS)}"
+                    )
+        return v
+
 
 class IgnoreSettingsSchema(BaseModel):
     """Schema for ignore settings."""
@@ -122,6 +136,7 @@ class SettingsSchema(BaseModel):
     severity_labels: dict[str, str | list[str]] = {}
     ignore_settings: IgnoreSettingsSchema = IgnoreSettingsSchema()
     documentation: DocumentationSettingsSchema = DocumentationSettingsSchema()
+    hide_severities: list[str] | None = None  # Global severity filtering
 
     @field_validator("fail_on_severity")
     @classmethod
@@ -134,6 +149,18 @@ class SettingsSchema(BaseModel):
                 )
         return v
 
+    @field_validator("hide_severities")
+    @classmethod
+    def validate_hide_severities(cls, v: list[str] | None) -> list[str] | None:
+        if v is not None:
+            for severity in v:
+                if severity not in SEVERITY_LEVELS:
+                    raise ValueError(
+                        f"Invalid severity in hide_severities: {severity}. "
+                        f"Must be one of: {sorted(SEVERITY_LEVELS)}"
+                    )
+        return v
+
 
 class CustomCheckSchema(BaseModel):
     """Schema for custom check definitions."""
@@ -446,6 +473,9 @@ class ConfigLoader:
             config: Loaded configuration
             registry: Check registry to configure
         """
+        # Get global hide_severities from settings (for fallback)
+        global_hide_severities = config.settings.get("hide_severities")
+
         # Configure built-in checks
         for check in registry.get_all_checks():
             check_id = check.check_id
@@ -455,6 +485,13 @@ class ConfigLoader:
             existing_config = registry.get_config(check_id)
             existing_enabled = existing_config.enabled if existing_config else True
 
+            # Parse hide_severities: per-check overrides global
+            hide_severities = check_config_dict.get("hide_severities")
+            if hide_severities is None:
+                hide_severities = global_hide_severities
+            if hide_severities is not None:
+                hide_severities = frozenset(hide_severities)
+
             # Create CheckConfig object
             # If there's explicit config, use it; otherwise preserve existing enabled state
             check_config = CheckConfig(
@@ -464,9 +501,8 @@ class ConfigLoader:
                 config=check_config_dict,
                 description=check_config_dict.get("description", check.description),
                 root_config=config.config_dict,  # Pass full config for cross-check access
-                ignore_patterns=check_config_dict.get(
-                    "ignore_patterns", []
-                ),  # NEW: Ignore patterns
+                ignore_patterns=check_config_dict.get("ignore_patterns", []),
+                hide_severities=hide_severities,
             )
 
             registry.configure_check(check_id, check_config)

iam_validator/core/config/defaults.py

@@ -110,6 +110,12 @@ DEFAULT_CONFIG = {
             # Include AWS documentation links alongside org docs
             "include_aws_docs": True,
         },
+        # Severity filtering - hide specific severity levels from output
+        # When set, issues with these severities will be filtered out globally
+        # Can be overridden per-check using check-level hide_severities
+        # Valid values: "error", "warning", "info", "critical", "high", "medium", "low"
+        # Example: ["low", "info"] - hide low and info severity findings
+        "hide_severities": None,
     },
     # ========================================================================
     # AWS IAM Validation Checks (17 checks total)

iam_validator/core/constants.py

@@ -77,6 +77,17 @@ MEDIUM_SEVERITY_LEVELS = ("warning", "medium")
 # Low severity issues (informational)
 LOW_SEVERITY_LEVELS = ("info", "low")
 
+# Severity configuration with emoji and action guidance for PR comments
+SEVERITY_CONFIG = {
+    "critical": {"emoji": "🔴", "action": "Block deployment"},
+    "high": {"emoji": "🟠", "action": "Fix before merge"},
+    "medium": {"emoji": "🟡", "action": "Address soon"},
+    "low": {"emoji": "🔵", "action": "Consider fixing"},
+    "error": {"emoji": "❌", "action": "Must fix - AWS will reject"},
+    "warning": {"emoji": "⚠️", "action": "Review"},
+    "info": {"emoji": "ℹ️", "action": "Optional"},
+}
+
 # ============================================================================
 # GitHub Integration
 # ============================================================================
@@ -161,10 +172,6 @@ AWS_TAG_KEY_ALLOWED_CHARS = r"a-zA-Z0-9 +\-=._:/@"
 # Maximum length for AWS tag keys (per AWS documentation)
 AWS_TAG_KEY_MAX_LENGTH = 128
 
-# Tag-key placeholder patterns used in AWS service definitions
-# These patterns indicate where a tag key should be substituted
-AWS_TAG_KEY_PLACEHOLDERS = ("/tag-key", "/${TagKey}", "/${tag-key}")
-
 # --- Tag Value Constraints ---
 # Allowed characters in AWS tag values: letters, numbers, spaces, and + - = . _ : / @
 # Same character set as tag keys

iam_validator/core/models.py

@@ -126,12 +126,24 @@ class Statement(BaseModel):
             return []
         return [self.action] if isinstance(self.action, str) else self.action
 
+    def get_not_actions(self) -> list[str]:
+        """Get list of NotAction values, handling both string and list formats."""
+        if self.not_action is None:
+            return []
+        return [self.not_action] if isinstance(self.not_action, str) else self.not_action
+
     def get_resources(self) -> list[str]:
         """Get list of resources, handling both string and list formats."""
         if self.resource is None:
             return []
         return [self.resource] if isinstance(self.resource, str) else self.resource
 
+    def get_not_resources(self) -> list[str]:
+        """Get list of NotResource values, handling both string and list formats."""
+        if self.not_resource is None:
+            return []
+        return [self.not_resource] if isinstance(self.not_resource, str) else self.not_resource
+
 
 class IAMPolicy(BaseModel):
     """IAM policy document."""
@@ -179,6 +191,8 @@ class ValidationIssue(BaseModel):
     documentation_url: str | None = None
     # Step-by-step remediation guidance
     remediation_steps: list[str] | None = None
+    # Risk category for classification (e.g., "privilege_escalation", "data_exfiltration")
+    risk_category: str | None = None
 
     # Severity level constants (ClassVar to avoid Pydantic treating them as fields)
     VALID_SEVERITIES: ClassVar[frozenset[str]] = frozenset(
@@ -226,18 +240,23 @@ class ValidationIssue(BaseModel):
         Returns:
             Formatted comment string
         """
-        severity_emoji = {
-            # IAM validity severities
-            "error": "❌",
-            "warning": "⚠️",
-            "info": "ℹ️",
-            # Security severities
-            "critical": "🔴",
-            "high": "🟠",
-            "medium": "🟡",
-            "low": "🔵",
-        }
-        emoji = severity_emoji.get(self.severity, "•")
+        # Get severity config with emoji and action guidance
+        severity_config = constants.SEVERITY_CONFIG.get(
+            self.severity, {"emoji": "•", "action": "Review"}
+        )
+        emoji = severity_config["emoji"]
+        action = severity_config["action"]
+
+        # Get risk category icon if available
+        from iam_validator.core.config.check_documentation import RISK_CATEGORY_ICONS
+
+        risk_icon = ""
+        if self.risk_category:
+            icon = RISK_CATEGORY_ICONS.get(self.risk_category, "")
+            if icon:
+                # Format risk category for display (e.g., "privilege_escalation" -> "Privilege Escalation")
+                category_display = self.risk_category.replace("_", " ").title()
+                risk_icon = f" | {icon} {category_display}"
 
         parts = []
 
@@ -263,13 +282,19 @@ class ValidationIssue(BaseModel):
                 )
                 parts.append(f"<!-- finding-id: {finding_hash} -->\n")
 
+        # Main issue header with severity, action guidance, and risk category
+        parts.append(f"{emoji} **{self.severity.upper()}** - {action}{risk_icon}")
+        parts.append("")
+
         # Build statement context for better navigation
         statement_context = f"Statement[{self.statement_index}]"
         if self.statement_sid:
             statement_context = f"`{self.statement_sid}` ({statement_context})"
+        if self.line_number:
+            statement_context = f"{statement_context} (line {self.line_number})"
 
-        # Main issue header with statement context
-        parts.append(f"{emoji} **{self.severity.upper()}** in **{statement_context}**")
+        # Statement context on its own line
+        parts.append(f"**Statement:** {statement_context}")
         parts.append("")
 
         # Show message immediately (not collapsed)