# AWS Security Remediation MCP Server

An MCP (Model Context Protocol) server that provides automated security incident remediation tools for AWS environments. Designed to work with GuardDuty findings for real-time threat response.

## Tools

| Tool | Description |
|------|-------------|
| `quarantine_s3_object` | Move a malicious S3 object to a quarantine bucket and delete the original |
| `restrict_iam_access` | Block all access for a compromised IAM user or role by attaching a deny-all policy |
| `update_security_group` | Remove overly permissive inbound rules (0.0.0.0/0) from a security group |

## Prerequisites

- Python 3.10+
- AWS credentials configured (environment variables, `~/.aws/credentials`, or IAM role)
- `QUARANTINE_BUCKET` environment variable set (required for `quarantine_s3_object`)

### Required IAM Permissions

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:CopyObject"
      ],
      "Resource": [
        "arn:aws:s3:::SOURCE-BUCKET/*",
        "arn:aws:s3:::QUARANTINE-BUCKET/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:PutUserPolicy",
        "iam:PutRolePolicy"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeSecurityGroups",
        "ec2:RevokeSecurityGroupIngress"
      ],
      "Resource": "*"
    }
  ]
}
```

## Installation

```bash
pip install -e .
```

## Usage

### As a CLI tool (stdio transport)

```bash
QUARANTINE_BUCKET=my-quarantine-bucket security-remediation-mcp-server
```

### With Claude Desktop / Amazon Q / Cline

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "security-remediation": {
      "command": "security-remediation-mcp-server",
      "env": {
        "QUARANTINE_BUCKET": "my-quarantine-bucket",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

### With Docker

```bash
docker build -t security-remediation-mcp-server .

docker run --rm \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_REGION=us-east-1 \
  -e QUARANTINE_BUCKET=my-quarantine-bucket \
  -p 8000:8000 \
  security-remediation-mcp-server
```

## Tool Details

### quarantine_s3_object

Moves a malicious S3 object to a quarantine bucket with a date-based path structure, then deletes the original.

**Parameters:**
- `bucket_name` (str): Source S3 bucket name
- `object_key` (str): Object key (path) to quarantine

**Example response:**
```json
{
  "action_type": "quarantine_s3_object",
  "status": "SUCCESS",
  "target_resource": "s3://source-bucket/malware.txt",
  "details": "Moved to quarantine bucket: s3://quarantine-bucket/2026/03/02/source-bucket/malware.txt"
}
```

### restrict_iam_access

Attaches an inline deny-all policy (`ACO-EmergencyDenyAll`) to an IAM user or role, immediately revoking all permissions.

**Parameters:**
- `principal_arn` (str): Full ARN of the IAM user or role

### update_security_group

Removes all inbound rules that allow traffic from `0.0.0.0/0` (any IP address).

**Parameters:**
- `security_group_id` (str): Security group ID (e.g., `sg-0123456789abcdef0`)

## Use Case: GuardDuty Automated Response

This MCP server is designed to be used with an AI agent that receives GuardDuty findings and automatically takes remediation actions:

1. GuardDuty detects a threat (e.g., malware in S3)
2. EventBridge routes the finding to an AI agent
3. Agent analyzes the finding and calls the appropriate tool
4. Tool executes the remediation (quarantine, block, cleanup)
5. Agent reports the result

## License

MIT