iam-policy-validator 1.9.0__tar.gz → 1.10.1__tar.gz

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.9.0
+Version: 1.10.1
 Summary: Validate AWS IAM policies for correctness and security using AWS Service Reference API
 Project-URL: Homepage, https://github.com/boogy/iam-policy-validator
 Project-URL: Documentation, https://github.com/boogy/iam-policy-validator/tree/main/docs

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/examples/configs/full-reference-config.yaml

@@ -154,6 +154,45 @@ settings:
     # - medium  # Uncomment to fail on medium severity
     # - warning  # Uncomment to fail on IAM validity warnings
 
+  # GitHub PR label mapping based on severity findings
+  # When issues with these severities are found, apply the corresponding labels to the PR
+  # If no issues with these severities exist, remove the labels if present
+  # This helps signal to reviewers if the PR is ready for final review
+  #
+  # Supports both single labels and lists of labels per severity:
+  #
+  # Single label per severity:
+  #   severity_labels:
+  #     error: "iam-validity-error"
+  #     critical: "security-critical"
+  #
+  # Multiple labels per severity:
+  #   severity_labels:
+  #     error: ["iam-error", "needs-fix"]
+  #     critical: ["security-critical", "needs-security-review"]
+  #
+  # Mixed (some single, some multiple):
+  #   severity_labels:
+  #     error: "iam-validity-error"
+  #     critical: ["security-critical", "needs-security-review"]
+  #
+  # Example use cases:
+  #   - Apply multiple labels for better categorization
+  #   - Apply "needs-security-review" when critical/high issues are found
+  #   - Apply "needs-fix" for any validation errors
+  #   - Remove all labels when issues are fixed
+  #
+  # Note: Requires GitHub integration (--github-comment or --github-review flags)
+  # Default: [] (empty list = disabled)
+  severity_labels:
+    error: "iam-validity-error"
+    critical: "iam-security-critical"
+    high: "iam-security-high"
+    # medium: "security-medium"  # Uncomment to label medium severity issues
+    # Multiple labels example:
+    # error: ["iam-validity-error", "needs-fix"]
+    # critical: ["security-critical", "needs-security-review"]
+
   # Template Variable Support (applies to all ARN validation checks)
   #
   # When enabled, the validator is POSITION-AWARE and supports ANY variable name

iam_policy_validator-1.10.1/examples/configs/github-labels-config.yaml

@@ -0,0 +1,116 @@
+# ============================================================================
+# IAM Policy Validator - GitHub PR Labels Configuration
+# ============================================================================
+# This configuration demonstrates automatic GitHub PR label management based
+# on validation severity findings.
+#
+# When validation finds issues with configured severities, it automatically
+# applies the corresponding labels to the PR. When those issues are fixed,
+# the labels are removed. This helps reviewers quickly understand the status
+# of the PR without reading through all the validation comments.
+# ============================================================================
+
+settings:
+  # Define which severities should cause the build to fail
+  fail_on_severity:
+    - error      # IAM validity errors (invalid actions, malformed ARNs, etc.)
+    - critical   # Critical security risks (e.g., full wildcard policies)
+    - high       # High severity security issues
+
+  # Map severity levels to GitHub PR labels
+  # When validation finds issues with these severities, it will:
+  #   1. Apply the corresponding label(s) to the PR
+  #   2. Remove the label(s) if no issues with that severity exist
+  #
+  # Supports both single labels and lists of labels per severity:
+  #   - Single: error: "iam-validity-error"
+  #   - Multiple: error: ["iam-validity-error", "needs-fix"]
+  #
+  # This provides visual feedback to reviewers about the PR status:
+  #   - Labels present = issues need to be fixed
+  #   - Labels removed = issues resolved, ready for review
+  severity_labels:
+    error: "iam-validity-error"      # Applied when IAM validity errors found
+    critical: "security-critical"    # Applied when critical security issues found
+    high: "security-high"            # Applied when high severity issues found
+
+    # Example with multiple labels per severity:
+    # error: ["iam-validity-error", "needs-fix"]
+    # critical: ["security-critical", "needs-security-review", "high-priority"]
+    # high: ["security-high", "needs-review"]
+
+# ============================================================================
+# Example GitHub Actions Workflow
+# ============================================================================
+# To use this feature in GitHub Actions:
+#
+# name: Validate IAM Policies
+#
+# on:
+#   pull_request:
+#     paths:
+#       - 'policies/**/*.json'
+#
+# permissions:
+#   contents: read
+#   pull-requests: write    # Required for labels
+#   issues: write          # Required for labels
+#
+# jobs:
+#   validate:
+#     runs-on: ubuntu-latest
+#     steps:
+#       - uses: actions/checkout@v4
+#
+#       - name: Validate IAM Policies
+#         env:
+#           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+#           GITHUB_REPOSITORY: ${{ github.repository }}
+#           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
+#         run: |
+#           pip install iam-policy-validator
+#           iam-validator validate \
+#             --path ./policies/ \
+#             --config examples/configs/github-labels-config.yaml \
+#             --github-comment \
+#             --github-review
+# ============================================================================
+
+# ============================================================================
+# Label Behavior Examples
+# ============================================================================
+# Scenario 1: Initial validation finds issues
+#   - Policy has invalid action (severity: error)
+#   - Policy has wildcard resource (severity: high)
+#   → Labels applied: "iam-validity-error", "security-high"
+#   → Reviewer sees: This PR needs fixes before review
+#
+# Scenario 2: Developer fixes the invalid action
+#   - Only wildcard resource remains (severity: high)
+#   → Labels applied: "security-high"
+#   → Labels removed: "iam-validity-error"
+#   → Reviewer sees: IAM validity is good, but security issue remains
+#
+# Scenario 3: Developer fixes all issues
+#   - No issues found
+#   → All labels removed
+#   → Reviewer sees: Clean PR, ready for final review
+# ============================================================================
+
+# ============================================================================
+# Additional Configuration
+# ============================================================================
+# You can customize individual checks below. For a comprehensive list of
+# all available checks and options, see:
+#   - examples/configs/full-reference-config.yaml
+#   - examples/configs/basic-config.yaml
+#   - examples/configs/strict-security.yaml
+# ============================================================================
+
+# Example: Disable specific checks
+# wildcard_resource:
+#   enabled: false
+
+# Example: Adjust severity levels
+# service_wildcard:
+#   severity: medium  # Default is "high"

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/iam_validator/__version__.py

@@ -3,7 +3,7 @@
 This file is the single source of truth for the package version.
 """
 
-__version__ = "1.9.0"
+__version__ = "1.10.1"
 # Parse version, handling pre-release suffixes like -rc, -alpha, -beta
 _version_base = __version__.split("-")[0]  # Remove pre-release suffix if present
 __version_info__ = tuple(int(part) for part in _version_base.split("."))

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/iam_validator/commands/validate.py

@@ -302,12 +302,17 @@ Examples:
             from iam_validator.core.config.config_loader import ConfigLoader
             from iam_validator.core.pr_commenter import PRCommenter
 
-            # Load config to get fail_on_severity setting
+            # Load config to get fail_on_severity and severity_labels settings
             config = ConfigLoader.load_config(config_path)
             fail_on_severities = config.get_setting("fail_on_severity", ["error", "critical"])
+            severity_labels = config.get_setting("severity_labels", {})
 
             async with GitHubIntegration() as github:
-                commenter = PRCommenter(github, fail_on_severities=fail_on_severities)
+                commenter = PRCommenter(
+                    github,
+                    fail_on_severities=fail_on_severities,
+                    severity_labels=severity_labels,
+                )
                 success = await commenter.post_findings_to_pr(
                     report,
                     create_review=getattr(args, "github_review", False),
@@ -426,12 +431,17 @@ Examples:
             from iam_validator.core.config.config_loader import ConfigLoader
             from iam_validator.core.pr_commenter import PRCommenter
 
-            # Load config to get fail_on_severity setting
+            # Load config to get fail_on_severity and severity_labels settings
             config = ConfigLoader.load_config(config_path)
             fail_on_severities = config.get_setting("fail_on_severity", ["error", "critical"])
+            severity_labels = config.get_setting("severity_labels", {})
 
             async with GitHubIntegration() as github:
-                commenter = PRCommenter(github, fail_on_severities=fail_on_severities)
+                commenter = PRCommenter(
+                    github,
+                    fail_on_severities=fail_on_severities,
+                    severity_labels=severity_labels,
+                )
                 success = await commenter.post_findings_to_pr(
                     report,
                     create_review=False,  # Already posted per-file reviews in streaming mode

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/iam_validator/core/aws_service/validators.py

@@ -280,9 +280,12 @@ class ServiceValidator:
                     "- `aws:RequestedRegion`\n"
                     "- `aws:SourceIp`\n"
                     "- `aws:SourceVpce`\n"
-                    "- `aws:UserAgent`\n"
+                    "- `aws:ResourceOrgID`\n"
+                    "- `aws:PrincipalOrgID`\n"
+                    "- `aws:SourceAccount`\n"
+                    "- `aws:PrincipalAccount`\n"
                     "- `aws:CurrentTime`\n"
-                    "- `aws:SecureTransport`\n"
+                    "- `aws:ResourceAccount`\n"
                     "- `aws:PrincipalArn`\n"
                     "- And many others"
                 )

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/iam_validator/core/config/defaults.py

@@ -75,6 +75,16 @@ DEFAULT_CONFIG = {
         # IAM Validity: error, warning, info
         # Security: critical, high, medium, low
         "fail_on_severity": list(constants.HIGH_SEVERITY_LEVELS),
+        # GitHub PR label mapping based on severity findings
+        # When issues with these severities are found, apply the corresponding labels
+        # If no issues with these severities exist, remove the labels if present
+        # Supports both single labels and lists of labels per severity
+        # Examples:
+        #   Single label per severity: {"error": "iam-validity-error", "critical": "security-critical"}
+        #   Multiple labels per severity: {"error": ["iam-error", "needs-fix"], "critical": ["security-critical", "needs-review"]}
+        #   Mixed: {"error": "iam-validity-error", "critical": ["security-critical", "needs-review"]}
+        # Default: {} (disabled)
+        "severity_labels": {},
     },
     # ========================================================================
     # AWS IAM Validation Checks (17 checks total)

iam_policy_validator-1.10.1/iam_validator/core/label_manager.py

@@ -0,0 +1,197 @@
+"""Label Manager for GitHub PR Labels based on Severity Findings.
+
+This module manages GitHub PR labels based on IAM policy validation severity findings.
+When validation finds issues with specific severities, it applies corresponding labels.
+When those severities are not found, it removes the labels if present.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from iam_validator.core.models import PolicyValidationResult, ValidationReport
+    from iam_validator.integrations.github_integration import GitHubIntegration
+
+logger = logging.getLogger(__name__)
+
+
+class LabelManager:
+    """Manages GitHub PR labels based on severity findings."""
+
+    def __init__(
+        self,
+        github: "GitHubIntegration",
+        severity_labels: dict[str, str | list[str]] | None = None,
+    ):
+        """Initialize label manager.
+
+        Args:
+            github: GitHubIntegration instance for API calls
+            severity_labels: Mapping of severity levels to label name(s)
+                           Supports both single labels and lists of labels per severity.
+                           Examples:
+                             - Single label per severity:
+                               {"error": "iam-validity-error", "critical": "security-critical"}
+                             - Multiple labels per severity:
+                               {"error": ["iam-error", "needs-fix"], "critical": ["security-critical", "needs-security-review"]}
+                             - Mixed:
+                               {"error": "iam-validity-error", "critical": ["security-critical", "needs-review"]}
+        """
+        self.github = github
+        self.severity_labels = severity_labels or {}
+
+    def is_enabled(self) -> bool:
+        """Check if label management is enabled.
+
+        Returns:
+            True if severity_labels is configured and GitHub is configured
+        """
+        return bool(self.severity_labels) and self.github.is_configured()
+
+    def _get_severities_in_results(self, results: list["PolicyValidationResult"]) -> set[str]:
+        """Extract all severity levels found in validation results.
+
+        Args:
+            results: List of PolicyValidationResult objects
+
+        Returns:
+            Set of severity levels found (e.g., {"error", "critical", "high"})
+        """
+        severities = set()
+        for result in results:
+            for issue in result.issues:
+                severities.add(issue.severity)
+        return severities
+
+    def _get_severities_in_report(self, report: "ValidationReport") -> set[str]:
+        """Extract all severity levels found in validation report.
+
+        Args:
+            report: ValidationReport object
+
+        Returns:
+            Set of severity levels found (e.g., {"error", "critical", "high"})
+        """
+        return self._get_severities_in_results(report.results)
+
+    def _determine_labels_to_apply(self, found_severities: set[str]) -> set[str]:
+        """Determine which labels should be applied based on found severities.
+
+        Args:
+            found_severities: Set of severity levels found in validation
+
+        Returns:
+            Set of label names to apply
+        """
+        labels_to_apply = set()
+        for severity, labels in self.severity_labels.items():
+            if severity in found_severities:
+                # Support both single labels and lists of labels
+                if isinstance(labels, list):
+                    labels_to_apply.update(labels)
+                else:
+                    labels_to_apply.add(labels)
+        return labels_to_apply
+
+    def _determine_labels_to_remove(self, found_severities: set[str]) -> set[str]:
+        """Determine which labels should be removed based on missing severities.
+
+        Args:
+            found_severities: Set of severity levels found in validation
+
+        Returns:
+            Set of label names to remove
+        """
+        labels_to_remove = set()
+        for severity, labels in self.severity_labels.items():
+            if severity not in found_severities:
+                # Support both single labels and lists of labels
+                if isinstance(labels, list):
+                    labels_to_remove.update(labels)
+                else:
+                    labels_to_remove.add(labels)
+        return labels_to_remove
+
+    async def manage_labels_from_results(
+        self, results: list["PolicyValidationResult"]
+    ) -> tuple[bool, int, int]:
+        """Manage PR labels based on validation results.
+
+        This method will:
+        1. Determine which severity levels are present in the results
+        2. Add labels for severities that are found
+        3. Remove labels for severities that are not found
+
+        Args:
+            results: List of PolicyValidationResult objects
+
+        Returns:
+            Tuple of (success, labels_added, labels_removed)
+        """
+        if not self.is_enabled():
+            logger.debug("Label management not enabled (no severity_labels configured)")
+            return (True, 0, 0)
+
+        # Get all severities found in results
+        found_severities = self._get_severities_in_results(results)
+        logger.debug(f"Found severities in results: {found_severities}")
+
+        # Determine which labels to apply/remove
+        labels_to_apply = self._determine_labels_to_apply(found_severities)
+        labels_to_remove = self._determine_labels_to_remove(found_severities)
+
+        logger.debug(f"Labels to apply: {labels_to_apply}")
+        logger.debug(f"Labels to remove: {labels_to_remove}")
+
+        # Get current labels on PR
+        current_labels = set(await self.github.get_labels())
+        logger.debug(f"Current PR labels: {current_labels}")
+
+        # Filter: only add labels that aren't already present
+        labels_to_add = labels_to_apply - current_labels
+
+        # Filter: only remove labels that are currently present
+        labels_to_actually_remove = labels_to_remove & current_labels
+
+        success = True
+        added_count = 0
+        removed_count = 0
+
+        # Add new labels
+        if labels_to_add:
+            logger.info(f"Adding labels to PR: {labels_to_add}")
+            if await self.github.add_labels(list(labels_to_add)):
+                added_count = len(labels_to_add)
+            else:
+                logger.error("Failed to add labels to PR")
+                success = False
+
+        # Remove old labels
+        for label in labels_to_actually_remove:
+            logger.info(f"Removing label from PR: {label}")
+            if await self.github.remove_label(label):
+                removed_count += 1
+            else:
+                logger.error(f"Failed to remove label: {label}")
+                success = False
+
+        if added_count > 0 or removed_count > 0:
+            logger.info(f"Label management complete: added {added_count}, removed {removed_count}")
+        else:
+            logger.debug("No label changes needed")
+
+        return (success, added_count, removed_count)
+
+    async def manage_labels_from_report(self, report: "ValidationReport") -> tuple[bool, int, int]:
+        """Manage PR labels based on validation report.
+
+        This is a convenience method that extracts results from the report
+        and calls manage_labels_from_results().
+
+        Args:
+            report: ValidationReport object
+
+        Returns:
+            Tuple of (success, labels_added, labels_removed)
+        """
+        return await self.manage_labels_from_results(report.results)

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/iam_validator/core/models.py

@@ -31,7 +31,7 @@ class ServiceInfo(BaseModel):
 class ActionDetail(BaseModel):
     """Details about an AWS IAM action."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
     name: str = Field(alias="Name")
     action_condition_keys: list[str] | None = Field(
@@ -45,7 +45,7 @@ class ActionDetail(BaseModel):
 class ResourceType(BaseModel):
     """Details about an AWS resource type."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
     name: str = Field(alias="Name")
     arn_formats: list[str] | None = Field(default=None, alias="ARNFormats")
@@ -68,7 +68,7 @@ class ResourceType(BaseModel):
 class ConditionKey(BaseModel):
     """Details about an AWS condition key."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
     name: str = Field(alias="Name")
     description: str | None = Field(default=None, alias="Description")
@@ -78,7 +78,7 @@ class ConditionKey(BaseModel):
 class ServiceDetail(BaseModel):
     """Detailed information about an AWS service."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
     name: str = Field(alias="Name")
     prefix: str | None = None  # Not always present in API response
@@ -106,7 +106,7 @@ class ServiceDetail(BaseModel):
 class Statement(BaseModel):
     """IAM policy statement."""
 
-    model_config = ConfigDict(populate_by_name=True, extra="allow")
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True, extra="allow")
 
     sid: str | None = Field(default=None, alias="Sid")
     effect: str | None = Field(default=None, alias="Effect")
@@ -136,7 +136,7 @@ class Statement(BaseModel):
 class IAMPolicy(BaseModel):
     """IAM policy document."""
 
-    model_config = ConfigDict(populate_by_name=True, extra="allow")
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True, extra="allow")
 
     version: str | None = Field(default=None, alias="Version")
     statement: list[Statement] | None = Field(default=None, alias="Statement")

{iam_policy_validator-1.9.0 → iam_policy_validator-1.10.1}/iam_validator/core/pr_commenter.py

@@ -13,7 +13,9 @@ from iam_validator.core.constants import (
     REVIEW_IDENTIFIER,
     SUMMARY_IDENTIFIER,
 )
+from iam_validator.core.label_manager import LabelManager
 from iam_validator.core.models import ValidationIssue, ValidationReport
+from iam_validator.core.report import ReportGenerator
 from iam_validator.integrations.github_integration import GitHubIntegration, ReviewEvent
 
 logger = logging.getLogger(__name__)
@@ -32,6 +34,7 @@ class PRCommenter:
         github: GitHubIntegration | None = None,
         cleanup_old_comments: bool = True,
         fail_on_severities: list[str] | None = None,
+        severity_labels: dict[str, str | list[str]] | None = None,
     ):
         """Initialize PR commenter.
 
@@ -40,16 +43,24 @@ class PRCommenter:
             cleanup_old_comments: Whether to clean up old bot comments before posting new ones
             fail_on_severities: List of severity levels that should trigger REQUEST_CHANGES
                                (e.g., ["error", "critical", "high"])
+            severity_labels: Mapping of severity levels to label name(s) for automatic label management
+                           Supports both single labels and lists of labels per severity.
+                           Examples:
+                             - Single: {"error": "iam-validity-error", "critical": "security-critical"}
+                             - Multiple: {"error": ["iam-error", "needs-fix"], "critical": ["security-critical", "needs-review"]}
+                             - Mixed: {"error": "iam-validity-error", "critical": ["security-critical", "needs-review"]}
         """
         self.github = github
         self.cleanup_old_comments = cleanup_old_comments
         self.fail_on_severities = fail_on_severities or ["error", "critical"]
+        self.severity_labels = severity_labels or {}
 
     async def post_findings_to_pr(
         self,
         report: ValidationReport,
         create_review: bool = True,
         add_summary_comment: bool = True,
+        manage_labels: bool = True,
     ) -> bool:
         """Post validation findings to a PR.
 
@@ -57,6 +68,7 @@ class PRCommenter:
             report: Validation report with findings
             create_review: Whether to create a PR review with line comments
             add_summary_comment: Whether to add a summary comment
+            manage_labels: Whether to manage PR labels based on severity findings
 
         Returns:
             True if successful, False otherwise
@@ -81,8 +93,6 @@ class PRCommenter:
 
         # Post summary comment (potentially as multiple parts)
         if add_summary_comment:
-            from iam_validator.core.report import ReportGenerator
-
             generator = ReportGenerator()
             comment_parts = generator.generate_github_comment_parts(report)
 
@@ -104,6 +114,18 @@ class PRCommenter:
                 logger.error("Failed to post review comments")
                 success = False
 
+        # Manage PR labels based on severity findings
+        if manage_labels and self.severity_labels:
+            label_manager = LabelManager(self.github, self.severity_labels)
+            label_success, added, removed = await label_manager.manage_labels_from_report(report)
+
+            if not label_success:
+                logger.error("Failed to manage PR labels")
+                success = False
+            else:
+                if added > 0 or removed > 0:
+                    logger.info(f"Label management: added {added}, removed {removed}")
+
         return success
 
     async def _post_review_comments(self, report: ValidationReport) -> bool:
@@ -288,7 +310,7 @@ class PRCommenter:
 
             return mapping
 
-        except Exception as e:
+        except Exception as e:  # pylint: disable=broad-exception-caught
             logger.warning(f"Could not parse {policy_file} for line mapping: {e}")
             return {}
 
@@ -369,7 +391,7 @@ class PRCommenter:
 
             return None
 
-        except Exception as e:
+        except Exception as e:  # pylint: disable=broad-exception-caught
             logger.debug(f"Could not search {policy_file}: {e}")
             return None
 
@@ -398,15 +420,20 @@ async def post_report_to_pr(
 
         report = ValidationReport.model_validate(report_data)
 
-        # Load config to get fail_on_severity setting
+        # Load config to get fail_on_severity and severity_labels settings
         from iam_validator.core.config.config_loader import ConfigLoader
 
         config = ConfigLoader.load_config(config_path)
         fail_on_severities = config.get_setting("fail_on_severity", ["error", "critical"])
+        severity_labels = config.get_setting("severity_labels", {})
 
         # Post to PR
         async with GitHubIntegration() as github:
-            commenter = PRCommenter(github, fail_on_severities=fail_on_severities)
+            commenter = PRCommenter(
+                github,
+                fail_on_severities=fail_on_severities,
+                severity_labels=severity_labels,
+            )
             return await commenter.post_findings_to_pr(
                 report,
                 create_review=create_review,
@@ -419,6 +446,6 @@ async def post_report_to_pr(
     except json.JSONDecodeError as e:
         logger.error(f"Invalid JSON in report file: {e}")
         return False
-    except Exception as e:
+    except Exception as e:  # pylint: disable=broad-exception-caught
         logger.error(f"Failed to post report to PR: {e}")
         return False