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

iam_validator/mcp/tools/org_config_tools.py

@@ -0,0 +1,263 @@
+"""Organization configuration tools for MCP server.
+
+This module provides the underlying implementations for MCP tools
+that manage session-wide validator configurations.
+
+The session config is used to control which checks are enabled, their
+severity levels, and other validator settings. All validation is done
+by the IAM validator's built-in checks - not by separate guardrail logic.
+"""
+
+from typing import Any
+
+from iam_validator.mcp.session_config import SessionConfigManager
+
+
+async def set_organization_config_impl(
+    config: dict[str, Any],
+) -> dict[str, Any]:
+    """Set session-wide validator configuration.
+
+    This sets the validator configuration for the MCP session. The config
+    uses the same format as the CLI validator's YAML configuration files.
+
+    Args:
+        config: Validator configuration dictionary. Supports:
+            - settings: Global settings (fail_on_severity, parallel, etc.)
+            - Check IDs as keys with enabled/severity/options
+
+    Returns:
+        Dictionary with success status, applied config, and any warnings
+
+    Example:
+        >>> await set_organization_config_impl({
+        ...     "settings": {"fail_on_severity": ["error", "critical"]},
+        ...     "wildcard_action": {"enabled": True, "severity": "critical"},
+        ...     "sensitive_action": {"enabled": False}
+        ... })
+    """
+    warnings: list[str] = []
+
+    try:
+        validator_config = SessionConfigManager.set_config(config, source="session")
+
+        # Return the applied settings for confirmation
+        applied_config = {
+            "settings": validator_config.settings,
+            "checks": validator_config.checks_config,
+        }
+
+        return {
+            "success": True,
+            "applied_config": applied_config,
+            "warnings": warnings,
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "applied_config": None,
+            "warnings": warnings,
+            "error": str(e),
+        }
+
+
+async def get_organization_config_impl() -> dict[str, Any]:
+    """Get the current session validator configuration.
+
+    Returns:
+        Dictionary with has_config, config, and source
+    """
+    config = SessionConfigManager.get_config()
+
+    if config is None:
+        return {
+            "has_config": False,
+            "config": None,
+            "source": "none",
+        }
+
+    return {
+        "has_config": True,
+        "config": {
+            "settings": config.settings,
+            "checks": config.checks_config,
+        },
+        "source": SessionConfigManager.get_config_source(),
+    }
+
+
+async def clear_organization_config_impl() -> dict[str, str]:
+    """Clear the session validator configuration.
+
+    Returns:
+        Dictionary with status
+    """
+    had_config = SessionConfigManager.clear_config()
+
+    return {
+        "status": "cleared" if had_config else "no_config_set",
+    }
+
+
+async def load_organization_config_from_yaml_impl(
+    yaml_content: str,
+) -> dict[str, Any]:
+    """Load validator configuration from YAML content.
+
+    Args:
+        yaml_content: YAML configuration string (same format as CLI config files)
+
+    Returns:
+        Dictionary with success status, applied config, warnings, and errors
+    """
+    try:
+        config, warnings = SessionConfigManager.load_from_yaml(yaml_content)
+
+        return {
+            "success": True,
+            "applied_config": {
+                "settings": config.settings,
+                "checks": config.checks_config,
+            },
+            "warnings": warnings,
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "applied_config": None,
+            "warnings": [],
+            "error": str(e),
+        }
+
+
+async def check_org_compliance_impl(
+    policy: dict[str, Any],
+) -> dict[str, Any]:
+    """Check if a policy passes validation with the session configuration.
+
+    This runs the full validator with the session configuration and returns
+    the validation results. It does NOT use separate guardrail logic - all
+    checking is done by the validator's built-in checks.
+
+    Args:
+        policy: IAM policy as a dictionary
+
+    Returns:
+        Dictionary with compliance status and validation issues
+    """
+    from iam_validator.mcp.tools.validation import validate_policy
+
+    config = SessionConfigManager.get_config()
+
+    if config is None:
+        # No session config - validate with defaults
+        result = await validate_policy(policy=policy, use_org_config=False)
+        return {
+            "compliant": result.is_valid,
+            "has_org_config": False,
+            "violations": [
+                {"type": issue.issue_type, "message": issue.message, "severity": issue.severity}
+                for issue in result.issues
+            ],
+            "warnings": ["No session config set - using default validator settings"],
+            "suggestions": [issue.suggestion for issue in result.issues if issue.suggestion],
+        }
+
+    # Validate with the session config
+    result = await validate_policy(policy=policy, use_org_config=True)
+
+    violations = [
+        {"type": issue.issue_type, "message": issue.message, "severity": issue.severity}
+        for issue in result.issues
+    ]
+
+    suggestions = [issue.suggestion for issue in result.issues if issue.suggestion]
+
+    return {
+        "compliant": result.is_valid,
+        "has_org_config": True,
+        "violations": violations,
+        "warnings": [],
+        "suggestions": suggestions,
+    }
+
+
+async def validate_with_config_impl(
+    policy: dict[str, Any],
+    config: dict[str, Any],
+    policy_type: str | None = None,
+) -> dict[str, Any]:
+    """Validate a policy with explicit inline configuration.
+
+    This runs validation with the provided config without affecting
+    the session configuration.
+
+    Args:
+        policy: IAM policy to validate
+        config: Inline configuration (same format as CLI config files)
+        policy_type: Type of policy. If None, auto-detects from policy structure.
+
+    Returns:
+        Dictionary with validation results
+    """
+    import tempfile
+    from pathlib import Path
+
+    import yaml
+
+    from iam_validator.mcp.tools.validation import validate_policy
+
+    # Create a temporary config file for the validator
+    temp_config_path: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+            yaml.dump(config, f)
+            temp_config_path = f.name
+
+        # Run validation with the temp config (bypasses session config)
+        validation_result = await validate_policy(
+            policy=policy,
+            policy_type=policy_type,
+            config_path=temp_config_path,
+            use_org_config=False,
+        )
+    except Exception as e:
+        return {
+            "is_valid": False,
+            "issues": [],
+            "error": str(e),
+            "config_applied": None,
+        }
+    finally:
+        if temp_config_path:
+            try:
+                Path(temp_config_path).unlink()
+            except OSError:
+                pass
+
+    # Build issues list
+    issues = [
+        {
+            "severity": issue.severity,
+            "message": issue.message,
+            "suggestion": issue.suggestion,
+            "check_id": issue.check_id,
+        }
+        for issue in validation_result.issues
+    ]
+
+    return {
+        "is_valid": validation_result.is_valid,
+        "issues": issues,
+        "config_applied": config,
+    }
+
+
+__all__ = [
+    "set_organization_config_impl",
+    "get_organization_config_impl",
+    "clear_organization_config_impl",
+    "load_organization_config_from_yaml_impl",
+    "check_org_compliance_impl",
+    "validate_with_config_impl",
+]

iam_validator/mcp/tools/query.py

@@ -0,0 +1,395 @@
+"""Query tools for the MCP server.
+
+This module provides query tools for querying AWS service definitions,
+listing validation checks, analyzing policies, and querying sensitive actions.
+"""
+
+from typing import Any
+
+from iam_validator.core.aws_service import AWSServiceFetcher
+from iam_validator.core.check_registry import create_default_registry
+from iam_validator.core.config.sensitive_actions import (
+    CREDENTIAL_EXPOSURE_ACTIONS,
+    DATA_ACCESS_ACTIONS,
+    PRIV_ESC_ACTIONS,
+    RESOURCE_EXPOSURE_ACTIONS,
+)
+from iam_validator.mcp.models import ActionDetails, PolicySummary
+from iam_validator.sdk import get_actions_by_access_level, parse_policy, query_arn_types
+from iam_validator.sdk import get_policy_summary as sdk_get_policy_summary
+from iam_validator.sdk import query_action_details as sdk_query_action_details
+from iam_validator.sdk import query_condition_keys as sdk_query_condition_keys
+
+
+async def query_service_actions(
+    service: str, access_level: str | None = None, fetcher: AWSServiceFetcher | None = None
+) -> list[str]:
+    """Get all actions for a service, optionally filtered by access level.
+
+    Args:
+        service: AWS service prefix (e.g., "s3", "iam", "ec2")
+        access_level: Optional filter by access level (read|write|list|tagging|permissions-management)
+        fetcher: Optional shared AWSServiceFetcher instance. If None, creates a new one.
+
+    Returns:
+        List of action names (e.g., ["s3:GetObject", "s3:PutObject"])
+
+    Example:
+        >>> actions = await query_service_actions("s3")
+        >>> write_actions = await query_service_actions("s3", "write")
+    """
+    # Use provided fetcher or create a new one
+    if fetcher is not None:
+        _fetcher = fetcher
+        should_close = False
+    else:
+        _fetcher = AWSServiceFetcher()
+        await _fetcher.__aenter__()
+        should_close = True
+
+    try:
+        if access_level:
+            # Validate access level
+            valid_levels = ["read", "write", "list", "tagging", "permissions-management"]
+            if access_level.lower() not in valid_levels:
+                raise ValueError(
+                    f"Invalid access level '{access_level}'. "
+                    f"Must be one of: {', '.join(valid_levels)}"
+                )
+            return await get_actions_by_access_level(_fetcher, service, access_level)  # type: ignore
+
+        # Get all actions (no filter)
+        from iam_validator.sdk import query_actions
+
+        actions = await query_actions(_fetcher, service)
+        return [action["action"] for action in actions]
+    finally:
+        if should_close:
+            await _fetcher.__aexit__(None, None, None)
+
+
+async def query_action_details(
+    action: str, fetcher: AWSServiceFetcher | None = None
+) -> ActionDetails | None:
+    """Get detailed information about a specific action.
+
+    Args:
+        action: Full action name (e.g., "s3:GetObject", "iam:CreateUser")
+        fetcher: Optional shared AWSServiceFetcher instance. If None, creates a new one.
+
+    Returns:
+        ActionDetails object with comprehensive action metadata, or None if not found
+
+    Example:
+        >>> details = await query_action_details("s3:GetObject")
+        >>> print(f"Access level: {details.access_level}")
+        >>> print(f"Resource types: {details.resource_types}")
+    """
+    # Parse service and action name
+    if ":" not in action:
+        raise ValueError(f"Invalid action format '{action}'. Expected 'service:action'")
+
+    service, action_name = action.split(":", 1)
+
+    # Use provided fetcher or create a new one
+    if fetcher is not None:
+        _fetcher = fetcher
+        should_close = False
+    else:
+        _fetcher = AWSServiceFetcher()
+        await _fetcher.__aenter__()
+        should_close = True
+
+    try:
+        try:
+            details = await sdk_query_action_details(_fetcher, service, action_name)
+
+            return ActionDetails(
+                action=details["action"],
+                service=details["service"],
+                access_level=details["access_level"],
+                resource_types=details["resource_types"],
+                condition_keys=details["condition_keys"],
+                description=details.get("description"),
+            )
+        except ValueError:
+            # Action not found
+            return None
+    finally:
+        if should_close:
+            await _fetcher.__aexit__(None, None, None)
+
+
+async def expand_wildcard_action(
+    pattern: str, fetcher: AWSServiceFetcher | None = None
+) -> list[str]:
+    """Expand wildcards like "s3:Get*" to specific actions.
+
+    Args:
+        pattern: Action pattern with wildcards (e.g., "s3:Get*", "iam:*User*")
+        fetcher: Optional shared AWSServiceFetcher instance. If None, creates a new one.
+
+    Returns:
+        List of matching action names
+
+    Example:
+        >>> actions = await expand_wildcard_action("s3:Get*")
+        >>> # Returns: ["s3:GetObject", "s3:GetObjectAcl", ...]
+    """
+    # Use provided fetcher or create a new one
+    if fetcher is not None:
+        _fetcher = fetcher
+        should_close = False
+    else:
+        _fetcher = AWSServiceFetcher()
+        await _fetcher.__aenter__()
+        should_close = True
+
+    try:
+        try:
+            return await _fetcher.expand_wildcard_action(pattern)
+        except Exception as e:
+            raise ValueError(f"Failed to expand wildcard action '{pattern}': {e}") from e
+    finally:
+        if should_close:
+            await _fetcher.__aexit__(None, None, None)
+
+
+async def query_condition_keys(service: str, fetcher: AWSServiceFetcher | None = None) -> list[str]:
+    """Get all condition keys for a service.
+
+    Args:
+        service: AWS service prefix (e.g., "s3", "iam")
+        fetcher: Optional shared AWSServiceFetcher instance. If None, creates a new one.
+
+    Returns:
+        List of condition key names (e.g., ["s3:prefix", "s3:x-amz-acl"])
+
+    Example:
+        >>> keys = await query_condition_keys("s3")
+        >>> print(f"S3 has {len(keys)} condition keys")
+    """
+    # Use provided fetcher or create a new one
+    if fetcher is not None:
+        _fetcher = fetcher
+        should_close = False
+    else:
+        _fetcher = AWSServiceFetcher()
+        await _fetcher.__aenter__()
+        should_close = True
+
+    try:
+        keys = await sdk_query_condition_keys(_fetcher, service)
+        return [key["condition_key"] for key in keys]
+    finally:
+        if should_close:
+            await _fetcher.__aexit__(None, None, None)
+
+
+async def query_arn_formats(
+    service: str, fetcher: AWSServiceFetcher | None = None
+) -> list[dict[str, Any]]:
+    """Get ARN formats for a service's resources.
+
+    Args:
+        service: AWS service prefix (e.g., "s3", "iam")
+        fetcher: Optional shared AWSServiceFetcher instance. If None, creates a new one.
+
+    Returns:
+        List of dictionaries with resource_type and arn_formats keys
+
+    Example:
+        >>> arns = await query_arn_formats("s3")
+        >>> for arn in arns:
+        ...     print(f"{arn['resource_type']}: {arn['arn_formats']}")
+    """
+    # Use provided fetcher or create a new one
+    if fetcher is not None:
+        _fetcher = fetcher
+        should_close = False
+    else:
+        _fetcher = AWSServiceFetcher()
+        await _fetcher.__aenter__()
+        should_close = True
+
+    try:
+        return await query_arn_types(_fetcher, service)
+    finally:
+        if should_close:
+            await _fetcher.__aexit__(None, None, None)
+
+
+async def list_checks() -> list[dict[str, Any]]:
+    """List all available validation checks with id, description, severity.
+
+    Returns:
+        List of dictionaries with check_id, description, and default_severity
+
+    Example:
+        >>> checks = await list_checks()
+        >>> for check in checks:
+        ...     print(f"{check['check_id']}: {check['description']}")
+    """
+    registry = create_default_registry()
+    checks = []
+
+    for check_id, check_instance in registry._checks.items():
+        checks.append(
+            {
+                "check_id": check_id,
+                "description": check_instance.description,
+                "default_severity": check_instance.default_severity,
+            }
+        )
+
+    # Sort by check_id for consistent ordering
+    return sorted(checks, key=lambda x: x["check_id"])
+
+
+async def get_policy_summary(policy: dict[str, Any]) -> PolicySummary:
+    """Analyze a policy and return summary statistics.
+
+    Args:
+        policy: IAM policy as a dictionary
+
+    Returns:
+        PolicySummary object with statistics about the policy
+
+    Example:
+        >>> summary = await get_policy_summary(policy_dict)
+        >>> print(f"Total statements: {summary.total_statements}")
+        >>> print(f"Services used: {summary.services_used}")
+    """
+    # Parse policy using SDK
+    iam_policy = parse_policy(policy)
+
+    # Get summary from SDK
+    summary = sdk_get_policy_summary(iam_policy)
+
+    # Extract services from actions
+    services = set()
+    for action in summary["actions"]:
+        if ":" in action:
+            service = action.split(":")[0]
+            services.add(service)
+
+    return PolicySummary(
+        total_statements=summary["statement_count"],
+        allow_statements=summary["allow_statements"],
+        deny_statements=summary["deny_statements"],
+        services_used=sorted(services),
+        actions_count=summary["action_count"],
+        has_wildcards=summary["has_wildcard_actions"] or summary["has_wildcard_resources"],
+        has_conditions=summary["condition_key_count"] > 0,
+    )
+
+
+async def list_sensitive_actions(category: str | None = None) -> list[str]:
+    """List sensitive actions, optionally filtered by category.
+
+    Args:
+        category: Optional category filter (credential_exposure|data_access|privilege_escalation|resource_exposure)
+
+    Returns:
+        List of sensitive action names
+
+    Example:
+        >>> all_sensitive = await list_sensitive_actions()
+        >>> credential_actions = await list_sensitive_actions("credential_exposure")
+    """
+    if category is None:
+        # Return all sensitive actions
+        all_actions = (
+            CREDENTIAL_EXPOSURE_ACTIONS
+            | DATA_ACCESS_ACTIONS
+            | PRIV_ESC_ACTIONS
+            | RESOURCE_EXPOSURE_ACTIONS
+        )
+        return sorted(all_actions)
+
+    # Normalize category name
+    category_lower = category.lower()
+
+    # Map category to action set
+    category_map = {
+        "credential_exposure": CREDENTIAL_EXPOSURE_ACTIONS,
+        "data_access": DATA_ACCESS_ACTIONS,
+        "privilege_escalation": PRIV_ESC_ACTIONS,
+        "priv_esc": PRIV_ESC_ACTIONS,  # Alias
+        "resource_exposure": RESOURCE_EXPOSURE_ACTIONS,
+    }
+
+    if category_lower not in category_map:
+        valid_categories = [k for k in category_map.keys() if not k.endswith("_esc")]
+        raise ValueError(
+            f"Invalid category '{category}'. Must be one of: {', '.join(valid_categories)}"
+        )
+
+    return sorted(category_map[category_lower])
+
+
+async def get_condition_requirements(action: str) -> dict[str, Any] | None:
+    """Get required conditions for an action.
+
+    This function checks if the action has any condition requirements
+    based on the condition requirements configuration.
+
+    Args:
+        action: Full action name (e.g., "iam:PassRole", "s3:GetObject")
+
+    Returns:
+        Dictionary with condition requirements including severity, suggestion_text,
+        and required_conditions, or None if no requirements found.
+
+    Example:
+        >>> req = await get_condition_requirements("iam:PassRole")
+        >>> if req:
+        ...     print(req["severity"])  # "high"
+        ...     print(req["suggestion_text"])  # Guidance on how to fix
+    """
+    import re
+
+    try:
+        from iam_validator.core.config.condition_requirements import (
+            CONDITION_REQUIREMENTS,
+        )
+    except ImportError:
+        return None
+
+    # CONDITION_REQUIREMENTS is a list of requirement dicts
+    # Each has either "actions" (list) or "action_patterns" (regex list)
+    for requirement in CONDITION_REQUIREMENTS:
+        # Check direct action match
+        if "actions" in requirement and action in requirement["actions"]:
+            return {
+                "action": action,
+                "severity": requirement.get("severity", "medium"),
+                "suggestion_text": requirement.get("suggestion_text", ""),
+                "required_conditions": requirement.get("required_conditions", []),
+            }
+
+        # Check pattern match
+        if "action_patterns" in requirement:
+            for pattern in requirement["action_patterns"]:
+                if re.match(pattern, action):
+                    return {
+                        "action": action,
+                        "severity": requirement.get("severity", "medium"),
+                        "suggestion_text": requirement.get("suggestion_text", ""),
+                        "required_conditions": requirement.get("required_conditions", []),
+                    }
+
+    return None
+
+
+__all__ = [
+    "query_service_actions",
+    "query_action_details",
+    "expand_wildcard_action",
+    "query_condition_keys",
+    "query_arn_formats",
+    "list_checks",
+    "get_policy_summary",
+    "list_sensitive_actions",
+    "get_condition_requirements",
+]