npm package: @modular-intelligence/cloud-security
Description: MCP server for multi-cloud security auditing (AWS, Azure, GCP)
Latest version: 1.0.2

# Cloud Security MCP Server

A comprehensive multi-cloud security auditing service that integrates with AWS, Azure, and GCP CLIs. This MCP (Model Context Protocol) server enables Claude to audit cloud infrastructure security posture, analyze access controls, review audit logs, and identify security misconfigurations across all major cloud providers.

## Overview

This server provides access to security auditing capabilities across three major cloud platforms through a unified read-only interface:

- **AWS** - CloudTrail event searches, GuardDuty threat detection, IAM analysis, S3 bucket exposure checks, security group audits
- **Azure** - Activity log monitoring, resource auditing
- **GCP** - Audit log analysis, project-wide security events

Perfect for cloud security assessments, compliance auditing, incident investigation, access control reviews, and infrastructure hardening.

## Tools

| Tool | Cloud Provider | Description |
|------|----------------|-------------|
| `cloudtrail_search` | AWS | Search AWS CloudTrail events for security-relevant activity |
| `guardduty_findings` | AWS | List and analyze AWS GuardDuty security findings |
| `iam_analyze` | AWS | Analyze AWS IAM for over-permissioned users and roles |
| `s3_public_check` | AWS | Check S3 bucket for public access exposure |
| `security_group_audit` | AWS | Audit AWS security group rules for overly permissive access |
| `azure_activity_log` | Azure | Search Azure Monitor activity log for events |
| `gcp_audit_log` | GCP | Search GCP audit logs for security events |

### CloudTrail Search

Search AWS CloudTrail for security-relevant events including user activity, API calls, and authentication events.

**Input Parameters:**
```typescript
{
  event_name: string     // Optional: CloudTrail event name to filter by
  username: string       // Optional: Username to filter by
  region: string         // AWS region (default: us-east-1)
  time_range: string     // Time range: 24h, 7d, or 30d (default: 24h)
  max_results: number    // Maximum results to return 1-100 (default: 20)
}
```

**Example Request:**
```json
{
  "event_name": "ConsoleLogin",
  "region": "us-east-1",
  "time_range": "7d",
  "max_results": 50
}
```

**Example Output:**
```json
{
  "Events": [
    {
      "EventId": "12345678-1234-1234-1234-123456789012",
      "EventName": "ConsoleLogin",
      "EventTime": "2024-01-15T10:30:45Z",
      "Username": "user@example.com",
      "Resources": [],
      "EventSource": "signin.amazonaws.com",
      "AWSRegion": "us-east-1",
      "CloudTrailEvent": "{\"eventVersion\":\"1.08\",\"eventTime\":\"2024-01-15T10:30:45Z\",\"sourceIPAddress\":\"192.0.2.1\"}"
    },
    {
      "EventId": "87654321-4321-4321-4321-210987654321",
      "EventName": "ConsoleLogin",
      "EventTime": "2024-01-14T15:22:10Z",
      "Username": "admin@example.com",
      "Resources": [],
      "EventSource": "signin.amazonaws.com",
      "AWSRegion": "us-east-1",
      "CloudTrailEvent": "{\"eventVersion\":\"1.08\",\"eventTime\":\"2024-01-14T15:22:10Z\",\"sourceIPAddress\":\"203.0.113.5\"}"
    }
  ],
  "NextToken": "eyJFeGVjdXRpb25JZCI6IjEyMzQ1Njc4In0="
}
```

### GuardDuty Findings

List and analyze AWS GuardDuty security findings from threat detection service.

**Input Parameters:**
```typescript
{
  detector_id: string    // GuardDuty detector ID (required)
  severity: string       // Optional: Filter by severity (low, medium, high)
  region: string         // AWS region (default: us-east-1)
  max_results: number    // Maximum results to return 1-100 (default: 20)
}
```

**Example Request:**
```json
{
  "detector_id": "12b0aac1d12a1e7e0a2b5c8d9e1f2a3b",
  "severity": "high",
  "region": "us-east-1",
  "max_results": 25
}
```

**Example Output:**
```json
{
  "Findings": [
    {
      "AccountId": "123456789012",
      "Arn": "arn:aws:guardduty:us-east-1:123456789012:detector/12b0aac1d12a1e7e0a2b5c8d9e1f2a3b/finding/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "Confidence": 98.0,
      "CreatedAt": "2024-01-15T10:30:45.000Z",
      "Description": "EC2 instance has the IMDSv1 metadata service enabled. This can allow an attacker with code execution to retrieve IAM credentials.",
      "FindingType": "UnauthorizedAccess:EC2/SSHBruteForce",
      "Id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "Partition": "aws",
      "Region": "us-east-1",
      "Resource": {
        "InstanceDetails": {
          "InstanceId": "i-1234567890abcdef0",
          "LaunchTime": "2024-01-10T14:22:33.000Z",
          "NetworkInterfaces": [
            {
              "Ipv6Addresses": [],
              "NetworkInterfaceId": "eni-12345678",
              "PrivateIpAddresses": [
                {
                  "PrivateIpAddress": "172.31.45.123"
                }
              ],
              "PublicDnsName": "ec2-203-0-113-5.compute-1.amazonaws.com",
              "PublicIp": "203.0.113.5",
              "SubnetId": "subnet-12345678",
              "VpcId": "vpc-12345678"
            }
          ]
        }
      },
      "SchemaVersion": "2.0",
      "Severity": 7.5,
      "Title": "EC2 instance i-1234567890abcdef0 has SSH brute force activity detected",
      "UpdatedAt": "2024-01-15T10:30:45.000Z"
    }
  ]
}
```

### IAM Analyze

Analyze AWS IAM users and roles to identify over-permissioned principals and security issues.

**Input Parameters:**
```typescript
{
  user_name: string      // Optional: Specific IAM user to analyze
  role_name: string      // Optional: Specific IAM role to analyze
  region: string         // AWS region (default: us-east-1)
}
```

**Example Request:**
```json
{
  "user_name": "developer",
  "region": "us-east-1"
}
```

**Example Output:**
```json
{
  "users": [
    {
      "UserName": "developer",
      "Arn": "arn:aws:iam::123456789012:user/developer",
      "AttachedPolicies": [
        {
          "PolicyName": "AdministratorAccess",
          "PolicyArn": "arn:aws:iam::aws:policy/AdministratorAccess"
        },
        {
          "PolicyName": "ReadOnlyAccess",
          "PolicyArn": "arn:aws:iam::aws:policy/ReadOnlyAccess"
        }
      ],
      "InlinePolicies": [
        "s3-access-policy",
        "lambda-invoke-policy"
      ],
      "IsOverPermissioned": true,
      "Reasons": [
        "Has AdministratorAccess policy attached",
        "Has 2 attached policies (potential over-permissioning)",
        "Has 2 inline policies (best practice: use managed policies)"
      ]
    }
  ],
  "summary": {
    "totalUsers": 1,
    "overPermissionedUsers": 1,
    "commonIssues": [
      "1 users with excessive permissions detected",
      "1 users have inline policies (use managed policies instead)"
    ]
  }
}
```

### S3 Public Check

Check AWS S3 buckets for public access exposure through ACLs, policies, and access block configuration.

**Input Parameters:**
```typescript
{
  bucket_name: string    // S3 bucket name (required, 3-63 chars, lowercase)
  region: string         // AWS region (default: us-east-1)
}
```

**Example Request:**
```json
{
  "bucket_name": "my-app-data-bucket",
  "region": "us-east-1"
}
```

**Example Output:**
```json
{
  "bucketName": "my-app-data-bucket",
  "isPublic": true,
  "findings": [
    "Bucket policy has 1 statement(s) with wildcard principal",
    "BlockPublicPolicy is not enabled",
    "RestrictPublicBuckets is not enabled"
  ],
  "acl": {
    "Owner": {
      "DisplayName": "owner-name",
      "ID": "79a3abb3738d6cb5be587f8efb2b7387c5cfe7e4c5e5b4c5a8b9c0d1e2f3a4b"
    },
    "Grants": [
      {
        "Grantee": {
          "Type": "Group",
          "URI": "http://acs.amazonaws.com/groups/global/AllUsers"
        },
        "Permission": "READ"
      }
    ]
  },
  "policy": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "PublicRead",
        "Effect": "Allow",
        "Principal": "*",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::my-app-data-bucket/*"
      }
    ]
  },
  "publicAccessBlock": {
    "BlockPublicAcls": true,
    "IgnorePublicAcls": true,
    "BlockPublicPolicy": false,
    "RestrictPublicBuckets": false
  }
}
```

### Security Group Audit

Audit AWS security group rules for overly permissive access patterns and dangerous port exposure.

**Input Parameters:**
```typescript
{
  group_id: string       // Optional: Specific security group ID to audit
  region: string         // AWS region (default: us-east-1)
  max_results: number    // Maximum results to return 1-100 (default: 20)
}
```

**Example Request:**
```json
{
  "region": "us-east-1",
  "max_results": 10
}
```

**Example Output:**
```json
{
  "summary": {
    "totalGroups": 2,
    "compliantGroups": 1,
    "nonCompliantGroups": 1,
    "totalFindings": 2
  },
  "audits": [
    {
      "groupId": "sg-12345678",
      "groupName": "default",
      "vpcId": "vpc-12345678",
      "findings": [
        "CRITICAL: Rule allows public access (0.0.0.0/0) to sensitive port(s) 22-22/tcp",
        "HIGH: Rule allows public access (0.0.0.0/0) to wide port range 443-8443/tcp"
      ],
      "riskyRules": [
        {
          "IpProtocol": "tcp",
          "FromPort": 22,
          "ToPort": 22,
          "IpRanges": [
            {
              "CidrIp": "0.0.0.0/0",
              "Description": "SSH access from anywhere"
            }
          ]
        }
      ],
      "isCompliant": false
    },
    {
      "groupId": "sg-87654321",
      "groupName": "app-server-sg",
      "vpcId": "vpc-87654321",
      "findings": [
        "No risky rules detected"
      ],
      "riskyRules": [],
      "isCompliant": true
    }
  ]
}
```

### Azure Activity Log

Search Azure Monitor activity log for events and activities across Azure resources.

**Input Parameters:**
```typescript
{
  resource_group: string // Optional: Resource group to filter by
  time_range: string     // Time range: 24h, 7d, or 30d (default: 24h)
  subscription: string   // Optional: Azure subscription ID
  max_results: number    // Maximum results to return 1-100 (default: 20)
}
```

**Example Request:**
```json
{
  "resource_group": "prod-resources",
  "time_range": "7d",
  "max_results": 30
}
```

**Example Output:**
```json
[
  {
    "eventTimestamp": "2024-01-15T10:30:45.123Z",
    "id": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/prod-resources/providers/Microsoft.Authorization/policyAssignments/12345678-1234-1234-1234-123456789012/events/12345678-1234-1234-1234-123456789012/ticks/638420346450000000",
    "resourceId": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/prod-resources/providers/Microsoft.Network/networkSecurityGroups/prod-nsg",
    "resourceGroupName": "prod-resources",
    "resourceProvider": {
      "value": "Microsoft.Network",
      "localizedValue": "Microsoft.Network"
    },
    "resourceType": {
      "value": "Microsoft.Network/networkSecurityGroups",
      "localizedValue": "Microsoft.Network/networkSecurityGroups"
    },
    "operationName": {
      "value": "Microsoft.Network/networkSecurityGroups/write",
      "localizedValue": "Write Network Security Group"
    },
    "status": {
      "value": "Succeeded",
      "localizedValue": "Succeeded"
    },
    "subStatus": {
      "value": "Created",
      "localizedValue": "Created"
    },
    "caller": "user@example.com",
    "correlationId": "12345678-1234-1234-1234-123456789012",
    "eventSource": {
      "value": "Administrative",
      "localizedValue": "Administrative"
    },
    "level": {
      "value": "Informational",
      "localizedValue": "Informational"
    }
  }
]
```

### GCP Audit Log

Search GCP audit logs for security and compliance events across projects and services.

**Input Parameters:**
```typescript
{
  project: string        // Optional: GCP project ID
  log_filter: string     // Optional: Additional log filter expression
  time_range: string     // Time range: 24h, 7d, or 30d (default: 24h)
  max_results: number    // Maximum results to return 1-100 (default: 20)
}
```

**Example Request:**
```json
{
  "project": "my-gcp-project",
  "log_filter": "protoPayload.methodName=compute.instances.delete",
  "time_range": "30d",
  "max_results": 15
}
```

**Example Output:**
```json
[
  {
    "insertId": "12345678-1234-1234-1234-123456789012",
    "logName": "projects/my-gcp-project/logs/cloudaudit.googleapis.com%2Factivity",
    "protoPayload": {
      "methodName": "compute.instances.delete",
      "resourceName": "projects/my-gcp-project/zones/us-central1-a/instances/web-server-1",
      "request": {
        "@type": "type.googleapis.com/compute.instances.delete"
      },
      "response": {
        "@type": "type.googleapis.com/operation"
      },
      "status": {
        "code": 0
      },
      "authenticationInfo": {
        "principalEmail": "user@example.com"
      },
      "requestMetadata": {
        "callerIp": "192.0.2.1",
        "userAgent": "gcloud-cli"
      },
      "serviceName": "compute.googleapis.com"
    },
    "receiveTimestamp": "2024-01-15T10:30:45.123Z",
    "severity": "NOTICE",
    "timestamp": "2024-01-15T10:30:44.123Z"
  },
  {
    "insertId": "87654321-4321-4321-4321-210987654321",
    "logName": "projects/my-gcp-project/logs/cloudaudit.googleapis.com%2Factivity",
    "protoPayload": {
      "methodName": "storage.buckets.setIamPolicy",
      "resourceName": "projects/_/buckets/my-data-bucket",
      "request": {
        "@type": "type.googleapis.com/storage.buckets.setIamPolicy"
      },
      "authenticationInfo": {
        "principalEmail": "admin@example.com"
      },
      "requestMetadata": {
        "callerIp": "203.0.113.5"
      },
      "serviceName": "storage.googleapis.com"
    },
    "receiveTimestamp": "2024-01-14T15:22:10.456Z",
    "severity": "NOTICE",
    "timestamp": "2024-01-14T15:22:09.456Z"
  }
]
```

## Configuration

### AWS CLI Authentication

This server requires the AWS CLI to be configured with appropriate credentials.

**Setup AWS CLI:**
```bash
aws configure
```

Or use environment variables:
```bash
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"
```

For detailed instructions, see: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html

### Azure CLI Authentication

Configure the Azure CLI with your credentials.

**Login to Azure:**
```bash
az login
```

For more information, see: https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli

### GCP CLI Authentication

Set up Google Cloud CLI authentication.

**Login to GCP:**
```bash
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
```

For detailed instructions, see: https://cloud.google.com/docs/authentication/gcloud

## Prerequisites

- Bun runtime (version 1.x or later) or Node.js 18+
- AWS CLI (for AWS tools)
- Azure CLI (for Azure tools)
- Google Cloud CLI (for GCP tools)
- Appropriate cloud credentials configured for each CLI

### Installation Commands

**AWS CLI:**
```bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
```

**Azure CLI:**
```bash
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
```

**Google Cloud CLI:**
```bash
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
gcloud init
```

## Installation

### Prerequisites

- Bun runtime (version 1.x or later)
- Node.js 18+ (alternative runtime)
- AWS CLI configured with credentials (for AWS tools)
- Azure CLI configured with credentials (for Azure tools)
- Google Cloud CLI configured with credentials (for GCP tools)

### Steps

1. Clone or download this repository:
```bash
git clone <repo-url>
cd cloud-security
```

2. Install dependencies:
```bash
bun install
```

3. Build the project:
```bash
bun run build
```

4. Ensure cloud CLIs are authenticated:
```bash
aws configure          # Configure AWS CLI
az login              # Login to Azure
gcloud auth login     # Login to GCP
```

5. Run the server:
```bash
bun run start
```

The server will start listening on stdio transport.

## Usage

### Running the Server

Start the server with Bun:

```bash
bun run src/index.ts
```

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

### Claude Desktop Configuration

Add the server to your Claude Desktop configuration at `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cloud-security": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/cloud-security/src/index.ts"
      ]
    }
  }
}
```

### Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in `.mcp.json` or via settings UI):

```json
{
  "servers": {
    "cloud-security": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/cloud-security/src/index.ts"]
    }
  }
}
```

### Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

**Request:**
"Audit my AWS security groups in us-east-1 for overly permissive rules"

**Claude will call:**
```json
{
  "tool": "security_group_audit",
  "input": {
    "region": "us-east-1",
    "max_results": 50
  }
}
```

**Request:**
"Check if my S3 bucket 'company-data' is publicly accessible"

**Claude will call:**
```json
{
  "tool": "s3_public_check",
  "input": {
    "bucket_name": "company-data",
    "region": "us-east-1"
  }
}
```

**Request:**
"Search CloudTrail for failed login attempts in the last 7 days"

**Claude will call:**
```json
{
  "tool": "cloudtrail_search",
  "input": {
    "event_name": "ConsoleLogin",
    "region": "us-east-1",
    "time_range": "7d",
    "max_results": 100
  }
}
```

**Request:**
"Analyze IAM users in my AWS account to find over-permissioned principals"

**Claude will call:**
```json
{
  "tool": "iam_analyze",
  "input": {
    "region": "us-east-1"
  }
}
```

**Request:**
"Get high severity GuardDuty findings from the last 30 days"

**Claude will call:**
```json
{
  "tool": "guardduty_findings",
  "input": {
    "detector_id": "12b0aac1d12a1e7e0a2b5c8d9e1f2a3b",
    "severity": "high",
    "region": "us-east-1"
  }
}
```

## Security

This server implements strict read-only enforcement and comprehensive input validation to prevent unauthorized cloud modifications and injection attacks.

### Read-Only Enforcement

All tools are strictly read-only and implement action-blocking at multiple levels:

**AWS CLI Blocking:**
- Blocked actions: delete, remove, terminate, modify, update, create, put, attach, detach, enable, disable, revoke, deregister, stop, start, reboot
- Only lookup, list, describe, and get operations allowed
- Examples of prevented operations:
  - Cannot delete instances, buckets, or security groups
  - Cannot modify IAM policies or users
  - Cannot create or update security groups
  - Cannot terminate EC2 instances

**Azure CLI Blocking:**
- Blocked actions: delete, create, update, set, start, stop, restart
- Only list and show operations allowed
- Prevents modification of Azure resources

**GCP CLI Blocking:**
- Blocked actions: delete, create, update, set, start, stop, deploy
- Only list and describe operations allowed
- Prevents creation or modification of GCP resources

### Input Validation

**Region Validation (AWS)**
- Validates against whitelist of official AWS regions
- Rejects invalid or custom region strings
- Supported regions: us-east-1, us-east-2, us-west-1, us-west-2, eu-west-1, eu-west-2, eu-west-3, eu-central-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, ap-south-1, sa-east-1, ca-central-1, me-south-1, af-south-1

**S3 Bucket Name Validation**
- Requires RFC 5321 compliant bucket names
- Minimum length: 3 characters
- Maximum length: 63 characters
- Character set: lowercase letters, numbers, dots, hyphens
- Must start and end with alphanumeric character

**Resource ID Validation**
- Alphanumeric characters, colons, slashes, hyphens only
- Maximum length: 500 characters
- Prevents command injection via resource identifiers

**CLI Argument Validation**
- Blocks shell metacharacters: semicolons, pipes, ampersands, backticks, dollar signs
- Prevents shell injection attacks
- Validates against malicious operator chaining

### What Gets Blocked

The server rejects:
- Write/delete/modify operations on AWS, Azure, or GCP resources
- Invalid or out-of-range AWS region specifications
- Malformed S3 bucket names
- Invalid resource identifiers with special characters
- Arguments containing shell metacharacters
- Oversized input parameters

### Error Handling

- Invalid inputs return descriptive error messages
- CLI errors are caught and reported
- Missing CLI tools trigger helpful configuration messages
- Command timeouts are handled gracefully (120-second default)
- Large output buffers (up to 10MB) prevent truncation

## License

ISC License - see LICENSE file for details