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

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')",
+    )