awslabs.iam-mcp-server 1.0.1__py3-none-any.whl

awslabs/__init__.py

@@ -0,0 +1,17 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""AWS Labs MCP Servers package."""
+
+__version__ = '1.0.0'

awslabs/iam_mcp_server/__init__.py

@@ -0,0 +1,17 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""AWS IAM MCP Server."""
+
+__version__ = '1.0.0'

awslabs/iam_mcp_server/aws_client.py

@@ -0,0 +1,84 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""AWS client utilities for the IAM MCP Server."""
+
+import boto3
+from awslabs.iam_mcp_server.context import Context
+from botocore.config import Config
+from loguru import logger
+from typing import Any, Optional
+
+
+def get_iam_client(region: Optional[str] = None) -> Any:
+    """Get an IAM client with proper configuration.
+
+    Args:
+        region: Optional AWS region override
+
+    Returns:
+        Configured IAM client
+
+    Raises:
+        Exception: If client creation fails
+    """
+    try:
+        # Use provided region, context region, or default
+        client_region = region or Context.get_region()
+
+        # Add user agent to identify this MCP server in AWS logs
+        config = Config(user_agent_extra='awslabs-iam-mcp-server/1.0.0')
+
+        if client_region:
+            logger.debug(f'Creating IAM client for region: {client_region}')
+            return boto3.client('iam', region_name=client_region, config=config)
+        else:
+            logger.debug('Creating IAM client with default region')
+            return boto3.client('iam', config=config)
+
+    except Exception as e:
+        logger.error(f'Failed to create IAM client: {e}')
+        raise Exception(f'Failed to create IAM client: {str(e)}')
+
+
+def get_aws_client(service_name: str, region: Optional[str] = None) -> Any:
+    """Get a generic AWS client for any service.
+
+    Args:
+        service_name: Name of the AWS service (e.g., 'iam', 's3', 'ec2')
+        region: Optional AWS region override
+
+    Returns:
+        Configured AWS client
+
+    Raises:
+        Exception: If client creation fails
+    """
+    try:
+        # Use provided region, context region, or default
+        client_region = region or Context.get_region()
+
+        # Add user agent to identify this MCP server in AWS logs
+        config = Config(user_agent_extra='awslabs-iam-mcp-server/1.0.0')
+
+        if client_region:
+            logger.debug(f'Creating {service_name} client for region: {client_region}')
+            return boto3.client(service_name, region_name=client_region, config=config)
+        else:
+            logger.debug(f'Creating {service_name} client with default region')
+            return boto3.client(service_name, config=config)
+
+    except Exception as e:
+        logger.error(f'Failed to create {service_name} client: {e}')
+        raise Exception(f'Failed to create {service_name} client: {str(e)}')

awslabs/iam_mcp_server/context.py

@@ -0,0 +1,50 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Context management for the AWS IAM MCP Server."""
+
+from typing import Optional
+
+
+class Context:
+    """Context class for managing server state and configuration."""
+
+    _readonly: bool = False
+    _region: Optional[str] = None
+
+    @classmethod
+    def initialize(cls, readonly: bool = False, region: Optional[str] = None):
+        """Initialize the context with configuration options.
+
+        Args:
+            readonly: Whether to run in read-only mode (prevents mutations)
+            region: AWS region to use for operations
+        """
+        cls._readonly = readonly
+        cls._region = region
+
+    @classmethod
+    def is_readonly(cls) -> bool:
+        """Check if the server is running in read-only mode."""
+        return cls._readonly
+
+    @classmethod
+    def get_region(cls) -> Optional[str]:
+        """Get the configured AWS region."""
+        return cls._region
+
+    @classmethod
+    def set_region(cls, region: str):
+        """Set the AWS region."""
+        cls._region = region

awslabs/iam_mcp_server/errors.py

@@ -0,0 +1,150 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Error handling utilities for the AWS IAM MCP Server."""
+
+from botocore.exceptions import ClientError as BotoClientError
+
+
+class IamMcpError(Exception):
+    """Base exception for IAM MCP Server errors."""
+
+    def __init__(self, message: str, error_code: str = 'IamMcpError'):
+        """Initialize the IAM MCP error.
+
+        Args:
+            message: Error message
+            error_code: Error code identifier
+        """
+        self.message = message
+        self.error_code = error_code
+        super().__init__(self.message)
+
+
+class IamClientError(IamMcpError):
+    """Exception for IAM client-side errors."""
+
+    def __init__(self, message: str):
+        """Initialize the IAM client error.
+
+        Args:
+            message: Error message
+        """
+        super().__init__(message, 'IamClientError')
+
+
+class IamPermissionError(IamMcpError):
+    """Exception for IAM permission-related errors."""
+
+    def __init__(self, message: str):
+        """Initialize the IAM permission error.
+
+        Args:
+            message: Error message
+        """
+        super().__init__(message, 'IamPermissionError')
+
+
+class IamResourceNotFoundError(IamMcpError):
+    """Exception for IAM resource not found errors."""
+
+    def __init__(self, message: str):
+        """Initialize the IAM resource not found error.
+
+        Args:
+            message: Error message
+        """
+        super().__init__(message, 'IamResourceNotFoundError')
+
+
+class IamValidationError(IamMcpError):
+    """Exception for IAM validation errors."""
+
+    def __init__(self, message: str):
+        """Initialize the IAM validation error.
+
+        Args:
+            message: Error message
+        """
+        super().__init__(message, 'IamValidationError')
+
+
+def handle_iam_error(error: Exception) -> IamMcpError:
+    """Handle IAM-specific errors and return standardized error responses.
+
+    Args:
+        error: The exception that was raised
+
+    Returns:
+        Standardized IAM MCP error
+    """
+    if isinstance(error, BotoClientError):
+        error_code = error.response.get('Error', {}).get('Code', 'Unknown')
+        error_message = error.response.get('Error', {}).get('Message', str(error))
+
+        # Handle common AWS IAM error patterns
+        if error_code in ['AccessDenied', 'AccessDeniedException']:
+            return IamPermissionError(
+                f'Access denied: {error_message}. Please check your AWS credentials and IAM permissions.'
+            )
+        elif error_code in ['NoSuchEntity', 'NoSuchEntityException']:
+            return IamResourceNotFoundError(f'Resource not found: {error_message}')
+        elif error_code in ['EntityAlreadyExists', 'EntityAlreadyExistsException']:
+            return IamClientError(f'Resource already exists: {error_message}')
+        elif error_code in ['InvalidInput', 'InvalidInputException', 'ValidationException']:
+            return IamValidationError(f'Invalid input: {error_message}')
+        elif error_code in ['LimitExceeded', 'LimitExceededException']:
+            return IamClientError(f'Limit exceeded: {error_message}')
+        elif error_code in ['ServiceFailure', 'ServiceFailureException']:
+            return IamMcpError(f'AWS service failure: {error_message}', 'ServiceFailure')
+        elif error_code in ['Throttling', 'ThrottlingException']:
+            return IamMcpError(f'Request throttled: {error_message}', 'Throttling')
+        elif error_code in ['IncompleteSignature']:
+            return IamClientError(
+                'Incomplete signature. The request signature does not conform to AWS standards.'
+            )
+        elif error_code in ['InvalidAction']:
+            return IamClientError(
+                'Invalid action. The action or operation requested is invalid. Verify that the action is typed correctly.'
+            )
+        elif error_code in ['InvalidClientTokenId']:
+            return IamClientError(
+                'Invalid client token ID. The X.509 certificate or AWS access key ID provided does not exist in our records.'
+            )
+        elif error_code in ['NotAuthorized']:
+            return IamPermissionError(
+                'Not authorized. The request signature we calculated does not match the signature you provided.'
+            )
+        elif error_code in ['RequestExpired']:
+            return IamClientError(
+                'Request expired. The request must be submitted within a valid time frame.'
+            )
+        elif error_code in ['SignatureDoesNotMatch']:
+            return IamClientError(
+                'Signature does not match. The request signature we calculated does not match the signature you provided.'
+            )
+        elif error_code in ['TokenRefreshRequired']:
+            return IamClientError(
+                'Token refresh required. The AWS access token needs to be refreshed.'
+            )
+        else:
+            return IamMcpError(f'AWS IAM Error ({error_code}): {error_message}', error_code)
+
+    elif isinstance(error, IamMcpError):
+        # Already a handled IAM MCP error, return as-is
+        return error
+
+    else:
+        # Generic error handling
+        return IamMcpError(f'Unexpected error: {str(error)}', 'UnexpectedError')

awslabs/iam_mcp_server/models.py

@@ -0,0 +1,197 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Data models for the AWS IAM MCP Server."""
+
+from pydantic import BaseModel, Field
+from typing import Any, Dict, List, Optional
+
+
+class IamUser(BaseModel):
+    """IAM User model."""
+
+    user_name: str = Field(..., description='The name of the IAM user')
+    user_id: str = Field(..., description='The unique identifier for the user')
+    arn: str = Field(..., description='The Amazon Resource Name (ARN) of the user')
+    path: str = Field(..., description='The path to the user')
+    create_date: str = Field(..., description='The date and time when the user was created')
+    password_last_used: Optional[str] = Field(
+        None, description="The date and time when the user's password was last used"
+    )
+
+
+class IamRole(BaseModel):
+    """IAM Role model."""
+
+    role_name: str = Field(..., description='The name of the IAM role')
+    role_id: str = Field(..., description='The unique identifier for the role')
+    arn: str = Field(..., description='The Amazon Resource Name (ARN) of the role')
+    path: str = Field(..., description='The path to the role')
+    create_date: str = Field(..., description='The date and time when the role was created')
+    assume_role_policy_document: Optional[str] = Field(
+        None, description='The trust policy document'
+    )
+    description: Optional[str] = Field(None, description='The description of the role')
+    max_session_duration: Optional[int] = Field(
+        None, description='Maximum session duration in seconds'
+    )
+
+
+class IamPolicy(BaseModel):
+    """IAM Policy model."""
+
+    policy_name: str = Field(..., description='The name of the policy')
+    policy_id: str = Field(..., description='The unique identifier for the policy')
+    arn: str = Field(..., description='The Amazon Resource Name (ARN) of the policy')
+    path: str = Field(..., description='The path to the policy')
+    default_version_id: str = Field(
+        ..., description='The identifier for the default version of the policy'
+    )
+    attachment_count: int = Field(..., description='The number of entities attached to the policy')
+    permissions_boundary_usage_count: int = Field(
+        0, description='The number of entities using this policy as a permissions boundary'
+    )
+    is_attachable: bool = Field(
+        ..., description='Whether the policy can be attached to users, groups, or roles'
+    )
+    description: Optional[str] = Field(None, description='The description of the policy')
+    create_date: str = Field(..., description='The date and time when the policy was created')
+    update_date: str = Field(..., description='The date and time when the policy was last updated')
+
+
+class AccessKey(BaseModel):
+    """IAM Access Key model."""
+
+    access_key_id: str = Field(..., description='The access key ID')
+    status: str = Field(..., description='The status of the access key (Active or Inactive)')
+    create_date: str = Field(..., description='The date and time when the access key was created')
+
+
+class AttachedPolicy(BaseModel):
+    """Attached Policy model."""
+
+    policy_name: str = Field(..., description='The name of the policy')
+    policy_arn: str = Field(..., description='The ARN of the policy')
+
+
+class UserDetailsResponse(BaseModel):
+    """Response model for detailed user information."""
+
+    user: IamUser = Field(..., description='User details')
+    attached_policies: List[AttachedPolicy] = Field(
+        default_factory=list, description='List of attached managed policies'
+    )
+    inline_policies: List[str] = Field(
+        default_factory=list, description='List of inline policy names'
+    )
+    groups: List[str] = Field(
+        default_factory=list, description='List of group names the user belongs to'
+    )
+    access_keys: List[AccessKey] = Field(
+        default_factory=list, description='List of access keys for the user'
+    )
+
+
+class UsersListResponse(BaseModel):
+    """Response model for listing users."""
+
+    users: List[IamUser] = Field(..., description='List of IAM users')
+    is_truncated: bool = Field(False, description='Whether the response is truncated')
+    marker: Optional[str] = Field(None, description='Marker for pagination')
+    count: int = Field(..., description='Number of users returned')
+
+
+class RolesListResponse(BaseModel):
+    """Response model for listing roles."""
+
+    roles: List[IamRole] = Field(..., description='List of IAM roles')
+    is_truncated: bool = Field(False, description='Whether the response is truncated')
+    marker: Optional[str] = Field(None, description='Marker for pagination')
+    count: int = Field(..., description='Number of roles returned')
+
+
+class PoliciesListResponse(BaseModel):
+    """Response model for listing policies."""
+
+    policies: List[IamPolicy] = Field(..., description='List of IAM policies')
+    is_truncated: bool = Field(False, description='Whether the response is truncated')
+    marker: Optional[str] = Field(None, description='Marker for pagination')
+    count: int = Field(..., description='Number of policies returned')
+
+
+class CreateUserResponse(BaseModel):
+    """Response model for creating a user."""
+
+    user: IamUser = Field(..., description='Created user details')
+    message: str = Field(..., description='Success message')
+
+
+class CreateRoleResponse(BaseModel):
+    """Response model for creating a role."""
+
+    role: IamRole = Field(..., description='Created role details')
+    message: str = Field(..., description='Success message')
+
+
+class CreateAccessKeyResponse(BaseModel):
+    """Response model for creating an access key."""
+
+    access_key_id: str = Field(..., description='The access key ID')
+    secret_access_key: str = Field(..., description='The secret access key')
+    status: str = Field(..., description='The status of the access key')
+    user_name: str = Field(..., description='The name of the user')
+    create_date: str = Field(..., description='The date and time when the access key was created')
+    message: str = Field(..., description='Success message')
+    warning: str = Field(..., description='Security warning about storing the secret key')
+
+
+class OperationResponse(BaseModel):
+    """Generic response model for operations."""
+
+    message: str = Field(..., description='Operation result message')
+    details: Optional[Dict[str, Any]] = Field(None, description='Additional operation details')
+
+
+class PolicyAttachmentResponse(BaseModel):
+    """Response model for policy attachment operations."""
+
+    message: str = Field(..., description='Operation result message')
+    user_name: Optional[str] = Field(None, description='The name of the user')
+    role_name: Optional[str] = Field(None, description='The name of the role')
+    policy_arn: str = Field(..., description='The ARN of the policy')
+
+
+class SimulationResult(BaseModel):
+    """Model for policy simulation result."""
+
+    eval_action_name: str = Field(..., description='The action that was evaluated')
+    eval_resource_name: str = Field(..., description='The resource that was evaluated')
+    eval_decision: str = Field(..., description='The result of the evaluation (Allow, Deny, etc.)')
+    matched_statements: List[Dict[str, Any]] = Field(
+        default_factory=list, description='Statements that matched'
+    )
+    missing_context_values: List[str] = Field(
+        default_factory=list, description='Context values that were missing'
+    )
+
+
+class PolicySimulationResponse(BaseModel):
+    """Response model for policy simulation."""
+
+    evaluation_results: List[SimulationResult] = Field(
+        ..., description='List of evaluation results'
+    )
+    is_truncated: bool = Field(False, description='Whether the response is truncated')
+    marker: Optional[str] = Field(None, description='Marker for pagination')
+    policy_source_arn: str = Field(..., description='ARN of the principal that was simulated')