iflow-mcp_aws-samples-security-assessment-mcp-server 0.1.0
AWS Well-Architected Security Assessment Tool MCP Server
Requires Python: >=3.10

# AWS Well-Architected Security Assessment Tool MCP Server (Sample Steamable-http Version)

This repository contains a sample implementation of the AWS Well-Architected Security Assessment Tool MCP Server. This server is designed to be used as a standalone application. In the Cloud Optimization Assistant Demo project, this server has been changed to support streamable HTTP communication, and deployed into Amazon Bedrock AgentCore Runtime.

## If you are looking for the official latest version of the AWS Well-Architected Security Assessment Tool MCP Server, please visit the [awslabs/mcp repo](https://github.com/awslabs/mcp)
[![PyPI version](https://img.shields.io/pypi/v/awslabs.well-architected-security-mcp-server.svg)](https://pypi.org/project/awslabs.well-architected-security-mcp-server/)

A Model Context Protocol (MCP) server that provides operational tools for monitoring and assessing AWS environments against the AWS Well-Architected Framework Security Pillar. This server enables AI assistants to help operations teams evaluate security posture, monitor compliance status, and optimize security costs while maintaining operational excellence according to the Well-Architected Framework.

## Features

- **Operational Security Monitoring**: Monitor status of AWS security services (GuardDuty, Security Hub, Inspector, IAM Access Analyzer) across your infrastructure
- **Security Operations Dashboard**: Retrieve and analyze security findings from AWS services for operational visibility
- **Compliance Operations**: Continuously assess security posture against Well-Architected Framework for operational compliance
- **Resource Operations**: Discover and monitor AWS resources across multiple services and regions for security operations
- **Cost-Effective Data Protection**: Monitor storage configuration for encryption compliance while optimizing security costs
- **Network Operations Security**: Verify network configuration for encryption compliance in operational environments
- **Compliance Monitoring**: Monitor compliance status of AWS resources against security standards for operational reporting
- **Security Operations Context**: Access stored security context data for operational analysis and trending

Operations teams can use the `CheckSecurityServices` tool to monitor if critical AWS security services are operational across their infrastructure. The `GetSecurityFindings` tool provides operational visibility into security findings, while `AnalyzeSecurityPosture` delivers comprehensive security operations reporting against the Well-Architected Framework. The `ExploreAwsResources` tool provides operational inventory capabilities across services and regions to ensure complete operational visibility and cost optimization of the AWS environment.

## Usage Environments

The AWS Well-Architected Security Assessment Tool MCP Server is designed for operational use across the following environments:

- **Production Operations**: Monitor security posture and compliance status in production environments for operational excellence.
- **Compliance Operations**: Perform ongoing compliance monitoring and reporting for regulatory and internal requirements.
- **Security Operations Center (SOC)**: Integrate with SOC workflows for continuous security monitoring and incident response.
- **Cost Optimization**: Monitor security service costs and optimize security spending while maintaining compliance.
- **Operational Reporting**: Generate security operations reports and dashboards for stakeholders and management.

**Operational Considerations**:
- **Automated Remediation**: While the tool provides operational visibility, automated remediation should be implemented through separate operational workflows.
- **Monitoring Integration**: Designed for integration with existing monitoring and alerting systems for comprehensive operational coverage.

**Important Note on Security Data**: When connecting to any environment, especially production, always prevent accidental exposure of sensitive security information.

## Operational Deployment Considerations

The AWS Well-Architected Security Assessment Tool MCP Server is designed for operational deployment across various environments with appropriate operational controls.

### Operational Use Cases

The tool is well-suited for operational deployment in the following scenarios:

1. **Security Operations Monitoring**: Continuous monitoring of security posture and compliance status
2. **Operational Compliance Reporting**: Regular compliance verification and reporting workflows
3. **Cost Operations**: Monitoring security service costs and optimizing security spending
4. **Operational Dashboards**: Integration with operational dashboards and monitoring systems

### Operational Best Practices

For optimal operational deployment:

1. **Rate Limiting**: Implement appropriate rate limiting to avoid impacting AWS API limits
2. **Monitoring Integration**: Integrate with existing operational monitoring and alerting systems
3. **Access Controls**: Implement proper IAM controls and operational access patterns
4. **Cost Monitoring**: Monitor API costs and optimize query patterns for cost efficiency

## Configuration

Add the AWS Well-Architected Security Assessment Tool MCP Server to your MCP client configuration:

```json
{
  "mcpServers": {
    "well-architected-security-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/well-architected-security-mcp-server/src/well-architected-security-mcp-server/awslabs/well_architected_security_mcp_server",
        "run",
        "server.py"
      ],
      "env": {
        "AWS_REGION": "your-aws-region",
        "FASTMCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}
```

## AWS Authentication

The MCP server supports multiple AWS authentication methods through an enhanced credential chain:

### Authentication Methods

1. **AssumeRole (Recommended for Cross-Account Access)**
   ```json
   {
     "env": {
       "AWS_ASSUME_ROLE_ARN": "arn:aws:iam::123456789012:role/SecurityAuditRole",
       "AWS_ASSUME_ROLE_SESSION_NAME": "mcp-security-session",
       "AWS_ASSUME_ROLE_EXTERNAL_ID": "unique-external-id",
       "AWS_REGION": "us-east-1"
     }
   }
   ```

2. **Environment Variables**
   ```json
   {
     "env": {
       "AWS_ACCESS_KEY_ID": "your-access-key",
       "AWS_SECRET_ACCESS_KEY": "your-secret-key",
       "AWS_SESSION_TOKEN": "your-session-token",
       "AWS_REGION": "us-east-1"
     }
   }
   ```

3. **Default AWS Credentials Chain**
   - IAM roles (EC2 instance profiles, ECS task roles, etc.)
   - AWS credentials file (`~/.aws/credentials`)
   - AWS config file (`~/.aws/config`)

### AssumeRole Configuration

For cross-account security assessments, configure AssumeRole using environment variables:

- `AWS_ASSUME_ROLE_ARN`: **Required** - The ARN of the IAM role to assume
- `AWS_ASSUME_ROLE_SESSION_NAME`: *Optional* - Custom session name (default: "mcp-server-session")
- `AWS_ASSUME_ROLE_EXTERNAL_ID`: *Optional* - External ID for enhanced security

**Example Cross-Account Setup:**
```bash
export AWS_ASSUME_ROLE_ARN="arn:aws:iam::TARGET-ACCOUNT:role/SecurityAuditRole"
export AWS_ASSUME_ROLE_EXTERNAL_ID="shared-secret-key-2024"
export AWS_REGION="us-east-1"
```

For detailed AssumeRole configuration, see [AssumeRole Configuration Guide](docs/assume-role-configuration.md).

## Security Controls

The AWS Well-Architected Security Assessment Tool MCP Server includes security controls in your MCP client configuration to limit access to sensitive data:

### IAM Best Practices

We strongly recommend creating dedicated IAM roles with least-privilege permissions when using the AWS Well-Architected Security Assessment Tool MCP Server:

1. **Create a dedicated IAM role** specifically for security assessment operations
2. **Apply least-privilege permissions** by attaching only the necessary read-only policies
3. **Use scoped-down resource policies** whenever possible
4. **Apply a permission boundary** to limit the maximum permissions

For detailed example IAM policies tailored for security assessment use cases, see the AWS documentation for each security service being analyzed.

## MCP Tools

### Security Operations Tools

These operational tools help you monitor and manage your AWS security posture against the Well-Architected Framework Security Pillar.

- **CheckSecurityServices**: Monitor AWS security services operational status
  - Monitors operational status of GuardDuty, Security Hub, Inspector, and IAM Access Analyzer
  - Identifies service availability across regions for operational visibility
  - Provides operational recommendations for maintaining security service coverage

- **GetSecurityFindings**: Operational security findings retrieval
  - Collects operational security findings from Security Hub, GuardDuty, and Inspector
  - Filters findings for operational prioritization by severity, resource type, or service
  - Provides operational context and cost-effective remediation guidance

- **GetResourceComplianceStatus**: Operational compliance monitoring
  - Monitors resources against security standards for operational compliance
  - Identifies non-compliant resources for operational remediation workflows
  - Provides compliance metrics and operational improvement recommendations

- **ValidateCredentialConfiguration**: AWS credential validation
  - Validates current AWS credential configuration including AssumeRole setup
  - Provides troubleshooting information for authentication issues
  - Displays session information and credential source details

- **GetStoredSecurityContext**: Historical security operations data
  - Retrieves historical security operations data for trend analysis
  - Enables operational comparison of security posture over time
  - Provides operational context for security findings and cost optimization

- **ExploreAwsResources**: Operational resource inventory
  - Discovers resources across AWS services for operational visibility
  - Maps resource relationships for operational security context
  - Identifies resources requiring operational security attention

- **AnalyzeSecurityPosture**: Comprehensive security operations analysis
  - Evaluates operational security posture against Well-Architected Framework
  - Provides operational recommendations for security improvements and cost optimization
  - Generates operational security metrics and prioritized action items

## Example Prompts

### Security Operations Monitoring

- "Monitor the operational status of AWS security services across my account"
- "Generate an operational security report against the Well-Architected Security Pillar"
- "Show me current security findings that require operational attention"
- "Monitor encryption compliance across my S3 buckets for operational reporting"
- "Verify network encryption compliance for operational security standards"

### Operational Resource Management

- "Provide an operational inventory of all resources in my AWS account"
- "Identify resources with security issues that need operational attention"
- "List all EC2 instances across regions for security operations review"
- "Monitor which resources are not compliant with operational security standards"

### Security Operations Analysis

- "Analyze operational security posture against Well-Architected best practices"
- "What security improvements should operations prioritize for cost optimization?"
- "Compare current security operations metrics with last month's operational baseline"
- "Generate an operational security dashboard for management reporting"
- "Monitor security service costs and recommend optimization opportunities"

## Requirements

- Python 3.10+
- AWS credentials with read-only permissions for security services
- For AssumeRole: IAM permissions to assume target roles
- For cross-account access: Properly configured trust relationships

## Testing

The AWS Well-Architected Security Assessment Tool MCP Server includes a comprehensive test suite to ensure functionality and reliability. The tests are organized by module and use pytest with mocks to avoid making actual AWS API calls.

### Test Structure

- `test_prompt_utils.py`: Tests for prompt template utilities
- `test_resource_utils.py`: Tests for AWS resource operations
- `test_storage_security.py`: Tests for storage encryption checks
- `test_network_security.py`: Tests for network security checks
- `test_security_services.py`: Tests for AWS security services

### Running Tests

The easiest way to run all tests is to use the provided script:

```bash
# Make the script executable if needed
chmod +x run_tests.sh

# Run the tests
./run_tests.sh
```

This script will:
1. Install required dependencies (pytest, pytest-asyncio, pytest-cov)
2. Run all tests with coverage reporting

For more detailed information about testing, see the tests/README.md file in the project repository.

## License
MIT-0