iam-policy-validator 1.14.7__py3-none-any.whl → 1.15.1__py3-none-any.whl

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)

iam_validator/mcp/__init__.py

@@ -0,0 +1,162 @@
+"""IAM Policy Validator MCP Server.
+
+This module provides an MCP (Model Context Protocol) server for AI assistants
+to interact with the IAM Policy Validator. It exposes tools for:
+- Validating IAM policies
+- Generating policies from templates or descriptions
+- Querying AWS service definitions
+- Managing session-wide policy configurations
+
+The server uses FastMCP and provides a security-first approach to policy generation.
+
+Configuration:
+    The MCP server uses the same configuration format as the CLI validator.
+    You can load configuration from a YAML file using --config or set it
+    programmatically using SessionConfigManager.
+"""
+
+from typing import TYPE_CHECKING
+
+from iam_validator.mcp.models import (
+    ActionDetails,
+    GenerationResult,
+    PolicySummary,
+    ValidationResult,
+)
+from iam_validator.mcp.session_config import (
+    CustomInstructionsManager,
+    SessionConfigManager,
+    merge_conditions,
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def create_server() -> "FastMCP":
+    """Create and configure the MCP server.
+
+    Returns:
+        FastMCP: Configured MCP server instance
+
+    Raises:
+        ImportError: If fastmcp is not installed
+    """
+    try:
+        from iam_validator.mcp.server import create_server as _create_server
+
+        return _create_server()
+    except ImportError as e:
+        raise ImportError(
+            "fastmcp is required for MCP server. Install with: uv sync --extra mcp"
+        ) from e
+
+
+def run_server() -> None:
+    """Run the MCP server.
+
+    This is the entry point for the iam-validator-mcp command.
+    Supports configuration and custom instructions at startup.
+
+    Usage:
+        iam-validator-mcp
+        iam-validator-mcp --config /path/to/config.yaml
+        iam-validator-mcp --instructions "Always require MFA for sensitive actions"
+        iam-validator-mcp --instructions-file /path/to/instructions.md
+
+    Custom instructions can also be set via:
+        - Environment variable: IAM_VALIDATOR_MCP_INSTRUCTIONS
+        - Config file: custom_instructions key in YAML config
+
+    Raises:
+        ImportError: If fastmcp is not installed
+    """
+    import argparse
+    import sys
+    from pathlib import Path
+
+    parser = argparse.ArgumentParser(
+        prog="iam-validator-mcp",
+        description="IAM Policy Validator MCP Server for AI assistants",
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        metavar="FILE",
+        help="Path to configuration YAML file to load at startup",
+    )
+    parser.add_argument(
+        "--instructions",
+        type=str,
+        metavar="TEXT",
+        help="Custom instructions to append to default LLM instructions",
+    )
+    parser.add_argument(
+        "--instructions-file",
+        type=str,
+        metavar="FILE",
+        help="Path to file containing custom instructions (markdown, txt)",
+    )
+    args = parser.parse_args()
+
+    # Load config if provided (may include custom_instructions)
+    if args.config:
+        config_path = Path(args.config)
+        if not config_path.exists():
+            print(f"Error: Config file not found: {args.config}", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            config, warnings = SessionConfigManager.load_from_file(str(config_path))
+
+            for warning in warnings:
+                print(f"Warning: {warning}", file=sys.stderr)
+
+            print(f"Loaded config from: {args.config}", file=sys.stderr)
+
+        except Exception as e:
+            print(f"Error loading config: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    # Load custom instructions from CLI arguments (overrides config/env)
+    if args.instructions_file:
+        instructions_path = Path(args.instructions_file)
+        if not instructions_path.exists():
+            print(
+                f"Error: Instructions file not found: {args.instructions_file}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        try:
+            CustomInstructionsManager.load_from_file(str(instructions_path))
+            print(f"Loaded instructions from: {args.instructions_file}", file=sys.stderr)
+        except Exception as e:
+            print(f"Error loading instructions: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.instructions:
+        CustomInstructionsManager.set_instructions(args.instructions, source="cli")
+        print("Custom instructions set from CLI argument", file=sys.stderr)
+
+    try:
+        from iam_validator.mcp.server import run_server as _run_server
+
+        _run_server()
+    except ImportError as e:
+        raise ImportError(
+            "fastmcp is required for MCP server. Install with: uv sync --extra mcp"
+        ) from e
+
+
+__all__ = [
+    "create_server",
+    "run_server",
+    "ValidationResult",
+    "GenerationResult",
+    "PolicySummary",
+    "ActionDetails",
+    "SessionConfigManager",
+    "CustomInstructionsManager",
+    "merge_conditions",
+]

iam_validator/mcp/models.py

@@ -0,0 +1,118 @@
+"""Pydantic models for MCP tool request/response types.
+
+This module defines MCP-specific models that extend the core validation models
+for use with the FastMCP server implementation.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from iam_validator.core.models import ValidationIssue
+
+
+class ValidationResult(BaseModel):
+    """Result of policy validation.
+
+    Used by validation tools to return validation status and issues found.
+    """
+
+    is_valid: bool = Field(
+        description="Whether the policy passed validation (no errors or warnings)"
+    )
+    issues: list[ValidationIssue] = Field(
+        default_factory=list, description="List of validation issues found"
+    )
+    policy_file: str | None = Field(
+        default=None, description="Path to the policy file that was validated"
+    )
+    policy_type_detected: str | None = Field(
+        default=None,
+        description="The policy type used for validation: 'identity', 'resource', or 'trust'. "
+        "Shows auto-detected type when policy_type was not explicitly provided.",
+    )
+
+
+class GenerationResult(BaseModel):
+    """Result of policy generation.
+
+    Returned by all policy generation tools (from description, template, or actions).
+    Always includes validation results and security notes.
+    """
+
+    policy: dict[str, Any] = Field(description="The generated IAM policy document")
+    validation: ValidationResult = Field(description="Validation results for the generated policy")
+    security_notes: list[str] = Field(
+        default_factory=list,
+        description="Security warnings and auto-applied conditions (e.g., 'Auto-added MFA condition')",
+    )
+    template_used: str | None = Field(
+        default=None, description="Name of the template used for generation (if applicable)"
+    )
+
+
+class PolicySummary(BaseModel):
+    """Summary of a policy's structure and contents.
+
+    Provides high-level statistics about a policy for quick analysis.
+    """
+
+    total_statements: int = Field(description="Total number of statements in the policy")
+    allow_statements: int = Field(description="Number of statements with Effect: Allow")
+    deny_statements: int = Field(description="Number of statements with Effect: Deny")
+    services_used: list[str] = Field(
+        default_factory=list, description="List of AWS services referenced (e.g., ['s3', 'ec2'])"
+    )
+    actions_count: int = Field(description="Total number of unique actions across all statements")
+    has_wildcards: bool = Field(
+        description="Whether the policy contains wildcard actions or resources"
+    )
+    has_conditions: bool = Field(description="Whether the policy contains any conditions")
+
+
+class ActionDetails(BaseModel):
+    """Details about an AWS action.
+
+    Returned by query tools to provide comprehensive information about an IAM action.
+    """
+
+    action: str = Field(description="Full action name (e.g., 's3:GetObject')")
+    service: str = Field(description="AWS service prefix (e.g., 's3', 'ec2')")
+    access_level: str = Field(
+        description="Access level category: Read, Write, List, Tagging, or Permissions management"
+    )
+    resource_types: list[str] = Field(
+        default_factory=list,
+        description="Resource types this action can be applied to (e.g., ['bucket', 'object'])",
+    )
+    condition_keys: list[str] = Field(
+        default_factory=list,
+        description="Condition keys that can be used with this action",
+    )
+    description: str | None = Field(
+        default=None, description="Human-readable description of what the action does"
+    )
+
+
+class EnforcementResult(BaseModel):
+    """Result of security enforcement on a policy.
+
+    Returned by the security enforcement layer after applying required conditions
+    and validating security constraints.
+    """
+
+    policy: dict[str, Any] = Field(
+        description="The policy after security enforcement (with auto-added conditions)"
+    )
+    warnings: list[str] = Field(
+        default_factory=list,
+        description="Security warnings for issues that were auto-fixed (e.g., 'Added MFA condition')",
+    )
+    errors: list[str] = Field(
+        default_factory=list,
+        description="Security errors that could not be auto-fixed (generation should fail)",
+    )
+    conditions_added: list[str] = Field(
+        default_factory=list,
+        description="List of conditions that were automatically added (e.g., 'aws:MultiFactorAuthPresent')",
+    )