Skip to content
Back to search

aws-security-mcp

A Model Context Protocol server that connects AI assistants like Claude to AWS security services, allowing them to autonomously query, inspect, and analyze AWS infrastructure for security issues and misconfigurations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/groovybugify--aws-security-mcp/badge.svg)](/listings/groovybugify--aws-security-mcp)

HTML

<a href="/listings/groovybugify--aws-security-mcp"><img src="/api/listings/groovybugify--aws-security-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Update config.yml**

  aws:
    region: "us-east-1"
    profile: {profileName}
    .
    .
    .

2. Configure your AWS Credentials via ~ local setup - aws sso ```bash $ aws configure sso SSO Session Name - email@example.com URL - https://yourDomain.awsapps.com/start/# Region - us-east-1 ``` - env variabls ```bash export AWS_ACCESS_KEY_ID= export export AWS_SECRET_ACCESS_KEY= export export AWS_SESSION_TOKEN= ```

3. **Run the following commands**

   git clone https://github.com/groovyBugify/aws-security-mcp.git
   uv venv
   source .venv/bin/activate
   uv pip install -r requirements.txt

3. **Configure MCP Client**

   # Install mcp-proxy
   uv tool install mcp-proxy

   # Check location of mcp-proxy
   which mcp-proxy

   # Add to Claude Desktop config
   {
     "mcpServers": {
       "aws-security": {
         "command": "/path/to/mcp-proxy",
         "args": ["http://localhost:8000/sse"]
       }
     }
   }

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 544 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AWS Security MCP
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  4. A Model Context Protocol (MCP) server that enables AI assistants to perform comprehensive AWS security analysis through natural language queries.
  5. ## Overview
  6. AWS Security MCP bridges AI assistants like Claude with AWS security services, enabling real-time infrastructure analysis through conversational queries. The system automatically discovers and analyzes resources across multiple AWS accounts, providing security insights without requiring deep AWS CLI knowledge.
  7. ### Key Capabilities
  8. - **Cross-Account Discovery**: Automatic detection and access to AWS Organization accounts
  9. - **Natural Language Interface**: Query AWS resources using plain English
  10. - **Security Analysis**: Integrated findings from GuardDuty, SecurityHub, and Access Analyzer
  11. - **Infrastructure Mapping**: Network topology, threat modelling, security review and blast radius analysis
  12. - **Log Analytics**: Athena-powered analysis of CloudTrail, VPC Flow Logs, and security events
  13. ## Prerequisites
  14. - **Python**: 3.11 or higher
  15. - **Package Manager**: [uv](https://docs.astral.sh/uv/getting-started/installation/)
  16. - **AWS Account**: With appropriate IAM permissions
  17. - **MCP Client**: Claude Desktop, Cline, or compatible client
  18. ### AWS Requirements
  19. MCP Server's AWS credentials must have the following permissions:
  20. #### Core MCP Permissions
  21. ```json
  22. {
  23. "Version": "2012-10-17",
  24. "Statement": [
  25. {
  26. "Sid": "CrossAccountAccess",
  27. "Effect": "Allow",
  28. "Action": [
  29. "sts:AssumeRole"
  30. ],
  31. "Resource": "arn:aws:iam::*:role/aws-security-mcp-cross-account-access"
  32. },
  33. {
  34. "Sid": "OrganizationDiscovery",
  35. "Effect": "Allow",
  36. "Action": [
  37. "organizations:ListAccounts"
  38. ],
  39. "Resource": "*"
  40. }
  41. ]
  42. }
  43. ```
  44. #### Athena Integration Permissions
  45. For advanced log analysis capabilities, additional permissions are required:
  46. ```json
  47. {
  48. "Version": "2012-10-17",
  49. "Statement": [
  50. {
  51. "Sid": "AthenaQueryExecution",
  52. "Effect": "Allow",
  53. "Action": [
  54. "athena:BatchGetQueryExecution",
  55. "athena:GetQueryExecution",
  56. "athena:GetQueryResults",
  57. "athena:GetWorkGroup",
  58. "athena:GetTableMetadata",
  59. "athena:ListQueryExecutions",
  60. "athena:StartQueryExecution",
  61. "athena:GetQueryResultsStream",
  62. "athena:GetDataCatalog",
  63. "athena:ListDataCatalogs",
  64. "athena:ListDatabases",
  65. "athena:ListTableMetadata"
  66. ],
  67. "Resource": "*"
  68. },
  69. {
  70. "Sid": "GlueCatalogAccess",
  71. "Effect": "Allow",
  72. "Action": [
  73. "glue:GetDatabase",
  74. "glue:GetDatabases",
  75. "glue:GetTable",
  76. "glue:GetTables",
  77. "glue:GetPartition",
  78. "glue:GetPartitions",
  79. "glue:BatchGetPartition"
  80. ],
  81. "Resource": "*"
  82. },
  83. {
  84. "Sid": "S3LogDataAccess",
  85. "Effect": "Allow",
  86. "Action": [
  87. "s3:GetObject",
  88. "s3:ListBucket"
  89. ],
  90. "Resource": [
  91. "arn:aws:s3:::your-cloudtrail-bucket/*",
  92. "arn:aws:s3:::your-cloudtrail-bucket",
  93. "arn:aws:s3:::your-vpc-flow-logs-bucket/*",
  94. "arn:aws:s3:::your-vpc-flow-logs-bucket",
  95. "arn:aws:s3:::your-security-logs-bucket/*",
  96. "arn:aws:s3:::your-security-logs-bucket"
  97. ]
  98. },
  99. {
  100. "Sid": "AthenaResultsAccess",
  101. "Effect": "Allow",
  102. "Action": [
  103. "s3:GetObject",
  104. "s3:ListBucket",
  105. "s3:PutObject"
  106. ],
  107. "Resource": [
  108. "arn:aws:s3:::your-athena-results-bucket/*",
  109. "arn:aws:s3:::your-athena-results-bucket"
  110. ]
  111. }
  112. ]
  113. }
  114. ```
  115. #### Required AWS Managed Policies
  116. **SecurityAudit Policy (Required)**
  117. Attach the AWS managed SecurityAudit policy to your MCP Server's IAM user or IAM role:
  118. ```
  119. Policy ARN: arn:aws:iam::aws:policy/SecurityAudit
  120. ```
  121. This policy provides comprehensive read-only access to AWS security services and is **essential** for AWS Security MCP functionality. It includes permissions for:
  122. - **IAM**: Users, roles, policies, access analysis
  123. - **EC2**: Security groups, instances, VPC configurations
  124. - **S3**: Bucket policies, ACLs, public access settings
  125. - **GuardDuty**: Findings, detectors, threat intelligence
  126. - **SecurityHub**: Security standards, compliance findings
  127. - **Access Analyzer**: IAM access analysis and findings
  128. - **Lambda**: Function configurations and permissions
  129. - **CloudFront**: Distribution security settings
  130. - **Route53**: DNS configurations and health checks
  131. - **WAF**: Web ACL rules and configurations
  132. - **All other security-related AWS services**
  133. **Optional Managed Policies**
  134. - **AthenaFullAccess**: `arn:aws:iam::aws:policy/AmazonAthenaFullAccess` (for simplified Athena log analysis)
  135. #### Important Notes
  136. - It's best to use this MCP Server with Claude Desktop Pro/Max Plan or any other platform that allows you to deal with token size greater than 100,000
  137. - Replace bucket names in the S3 permissions with your actual CloudTrail, VPC Flow Logs, and Athena results bucket names
  138. - The SecurityAudit policy is **mandatory** for basic AWS Security MCP functionality
  139. - Athena integration permissions are optional and only required for advanced log analysis features
  140. - All permissions follow the principle of least privilege with read-only access where possible
  141. ## Quick Start ~ local setup
  142. 1. **Update config.yml**
  143. ```
  144. aws:
  145. region: "us-east-1"
  146. profile: {profileName}
  147. .
  148. .
  149. .
  150. ```
  151. 2. Configure your AWS Credentials via ~ local setup
  152. - aws sso
  153. ```bash
  154. $ aws configure sso
  155. SSO Session Name - email@example.com
  156. URL - https://yourDomain.awsapps.com/start/#
  157. Region - us-east-1
  158. ```
  159. - env variabls
  160. ```bash
  161. export AWS_ACCESS_KEY_ID=
  162. export export AWS_SECRET_ACCESS_KEY=
  163. export export AWS_SESSION_TOKEN=
  164. ```
  165. 3. **Run the following commands**
  166. ```bash
  167. git clone https://github.com/groovyBugify/aws-security-mcp.git
  168. uv venv
  169. source .venv/bin/activate
  170. uv pip install -r requirements.txt
  171. ```
  172. 3. **Configure MCP Client**
  173. ```bash
  174. # Install mcp-proxy
  175. uv tool install mcp-proxy
  176. # Check location of mcp-proxy
  177. which mcp-proxy
  178. # Add to Claude Desktop config
  179. {
  180. "mcpServers": {
  181. "aws-security": {
  182. "command": "/path/to/mcp-proxy",
  183. "args": ["http://localhost:8000/sse"]
  184. }
  185. }
  186. }
  187. ```
  188. ## Quick Start ~ as AWS ECS Service
  189. 1. **Login to AWS ECR**
  190. ```bash
  191. $ aws ecr get-login-password --region {region} | docker login --username AWS --password-stdin {accountID}.dkr.ecr.{region}.amazonaws.com
  192. ```
  193. 2. **Create ECR Repo**
  194. ```bash
  195. $ aws ecr create-repository --repository-name aws-security-mcp --region {region}
  196. ```
  197. 3. **Build Docker Image**
  198. ```bash
  199. $ cd aws-security-mcp/
  200. $ docker buildx build --platform linux/amd64 -t aws-security-mcp .
  201. $ docker tag aws-security-mcp:latest {accountID}.dkr.ecr.{region}.amazonaws.com/aws-security-mcp:latest
  202. $ docker push {accountID}.dkr.ecr.{region}.amazonaws.com/aws-security-mcp:latest
  203. ```
  204. 4. **Deploying as AWS ECS Service**
  205. - Create a Task Definition with "2048" CPU and "4096" Memory, this is optional, you can choose any values
  206. - Configure the Task definition to do port mapping for port 8000
  207. - Create ECS Task Role with the following permissions
  208. - SecurityAudit IAM Policy
  209. - Athena Access (Policy mentioned above)
  210. - STS Assume Role permissions to assume cross account roles
  211. - Create ECS Task Execution Role with basic permissions
  212. - Once the Task Definition is completed.
  213. - Create an AWS ECS Service using the Task definition
  214. - You can configure Load Balancer as well
  215. - Make Sure to turn off the Stickness Session on Load Balancers
  216. - Register the ALB's taget group and listeners for port 80/443 -> ECS Service(8000)
  217. - Register the ALB for Route53 domain.
  218. 5. **Configure MCP Client**
  219. ```bash
  220. # Install mcp-proxy
  221. uv tool install mcp-proxy
  222. # Check location of mcp-proxy
  223. which mcp-proxy
  224. # Add to Claude Desktop config
  225. {
  226. "mcpServers": {
  227. "aws-security": {
  228. "command": "/path/to/mcp-proxy",
  229. "args": ["http://{alb}/sse"]
  230. }
  231. }
  232. }
  233. ```
  234. ## Configuration
  235. ### YAML Configuration
  236. Edit `config.yaml` in the project root according to your needs:
  237. ```yaml
  238. aws:
  239. region: "us-east-1"
  240. profile: null
  241. server:
  242. log_level: "info"
  243. startup_quiet: false
  244. tool_quiet: false
  245. cross_account:
  246. role_name: "aws-security-mcp-cross-account-access"
  247. auto_setup_on_startup: true
  248. max_concurrent_assumptions: 5
  249. ```
  250. ### Environment Variable Override
  251. Environment variables take precedence over YAML configuration:
  252. ```bash
  253. export MCP_LOG_LEVEL=debug
  254. export MCP_STARTUP_QUIET=false
  255. export AWS_DEFAULT_REGION=eu-west-1
  256. ```
  257. ## Usage Examples
  258. ### Basic Infrastructure Queries
  259. ```
  260. Query: "Can you share a list of running ec2 instances?"
  261. Query: "Share all the secrets stored on env variables of Lambda functions, and share a list of functions for remediating this issue."
  262. Query: "Check my 'prod-ecs-cluster' and share more details about the 'user-login' service, is it deployed?"
  263. ```
  264. ### Security Analysis
  265. ```
  266. Query: "Show all GuardDuty findings from the last 7 days, and priortise based on the risk of exposure."
  267. Query: "Analyze IAM roles with administrative privileges"
  268. Query: "Generate blast radius analysis for IP 172.16.1.10"
  269. Query: "Fetch more details about the ip - 172.22.141.11, and share a network map for this resource.
  270. ```
  271. ### Cross-Account Operations
  272. ```
  273. Query: "List all connected AWS accounts"
  274. Query: "Refresh my AWS session"
  275. Query: "Find resources tagged Team:Security across all accounts"
  276. Query: "Show compliance status across organization"
  277. ```
  278. ## Architecture
  279. ### Cross-Account Access
  280. AWS Security MCP implements a hub-and-spoke model for multi-account access:
  281. 1. **Discovery**: Uses `organizations:ListAccounts` to identify target accounts
  282. 2. **Role Assumption**: Assumes `aws-security-mcp-cross-account-access` role in each account
  283. 3. **Session Management**: Maintains temporary credentials with automatic refresh
  284. 4. **Fallback**: Uses default credential chain for non-organization accounts
  285. ### Required IAM Role Setup
  286. Create this role in each target AWS account:
  287. **Role Name**: `aws-security-mcp-cross-account-access`
  288. **Trust Policy**:
  289. ```json
  290. {
  291. "Version": "2012-10-17",
  292. "Statement": [
  293. {
  294. "Effect": "Allow",
  295. "Principal": {
  296. "AWS": "arn:aws:iam::YOUR-MASTER-ACCOUNT-ID:root"
  297. },
  298. "Action": "sts:AssumeRole"
  299. }
  300. ]
  301. }
  302. ```
  303. **Permissions**: Attach AWS managed policy `arn:aws:iam::aws:policy/SecurityAudit`
  304. ## Athena Integration
  305. ### Overview
  306. AWS Security MCP integrates with Amazon Athena to provide advanced log analysis capabilities. This feature requires pre-existing Athena tables containing your security-relevant logs.
  307. ### Supported Log Types
  308. While the MCP server can analyze any log source through Athena, the following sources are recommended to provide comprehensive security metadata to your MCP client. For optimal security coverage, we recommend implementing at least CloudTrail and VPC Flow Logs:
  309. **Recommended Log Sources:**
  310. - **AWS CloudTrail**: API call auditing and user activity tracking
  311. - **VPC Flow Logs**: Network traffic pattern analysis
  312. - **CloudFront Logs**: CDN request and response analysis
  313. - **ALB Access Logs**: Application load balancer traffic insights
  314. - **WAF Logs**: Web application firewall events and blocks(Cloudflare/AWS WAF/Akamai)
  315. - **AWS Shield Logs**: DDoS protection and mitigation events
  316. **Flexibility for Custom Log Sources**
  317. The MCP server supports querying any log type stored in S3, giving you complete flexibility to analyze custom or additional log sources. To enable analysis of any log source, ensure:
  318. 1. **S3 Storage**: Your logs are stored in an S3 bucket
  319. 2. **Athena Table**: A properly configured Athena table exists for the log format
  320. 3. **IAM Permissions**: The MCP server has `s3:GetObject` and `s3:ListBucket` permissions for the target bucket
  321. This architecture allows you to extend security analysis beyond standard AWS logs to include application logs, custom security events, or third-party security tool outputs.
  322. ### Query Capabilities
  323. Once tables are configured, you can perform advanced queries:
  324. ```
  325. Query: "Show all failed login attempts from external IPs in the last 24 hours"
  326. Query: "Can you share what did 'saransh.rana@company.com' did in past 24 hours on my aws account? and share a timeline report?"
  327. Query: "Can you check for all the 'Access Denied/Error/Forbidden' on my PCI(123456789012) aws account and share the username and userIP of the principal, and do a reverse IP checkup if this IP is coming from my own AWS Org or external party."
  328. Query: "Correlate GuardDuty findings with CloudTrail and VPC Flow logs events"
  329. ```
  330. ### Setup Prerequisites
  331. 1. **S3 Buckets**: CloudTrail and VPC Flow Logs must be stored in S3
  332. 2. **Athena Workgroup**: Configure appropriate workgroup with result location
  333. 3. **Partitioning**: Enable partition projection for performance
  334. 4. **IAM Permissions**: Grant Athena query permissions to the MCP execution role
  335. ## Supported AWS Services
  336. ### Currently Available
  337. | Service | Capabilities |
  338. |---------|-------------|
  339. | **IAM** | Users, roles, policies, access keys, permission analysis |
  340. | **EC2** | Instances, security groups, VPCs, subnets, network interfaces |
  341. | **S3** | Buckets, permissions, public access analysis |
  342. | **GuardDuty** | Findings, detectors, threat intelligence |
  343. | **SecurityHub** | Findings, compliance standards, security scores |
  344. | **Lambda** | Functions, permissions, configurations, triggers |
  345. | **CloudFront** | Distributions, origins, behaviors, security policies |
  346. | **ELB/ALB/NLB** | Load balancers, target groups, listeners, health checks |
  347. | **Route53** | Hosted zones, DNS records, health checks |
  348. | **WAF** | Web ACLs, rules, rate limiting |
  349. | **Shield** | DDoS protection status and metrics |
  350. | **Access Analyzer** | IAM access analysis and findings |
  351. | **ECS/ECR** | Container services, repositories, image scanning |
  352. | **Organizations** | Account structure, SCPs, organizational units |
  353. | **Athena** | Log analysis, security event correlation |
  354. ### Planned Additions
  355. - Oauth Authentication
  356. - AWS Config compliance analysis
  357. - AWS Security Hub CSPM integration
  358. - External CSPM integration
  359. ## Advanced Configuration
  360. ### Production Deployment
  361. For production environments, use the following configuration:
  362. ```yaml
  363. server:
  364. host: "0.0.0.0"
  365. log_level: "error"
  366. startup_quiet: true
  367. tool_quiet: true
  368. minimal_logging: true
  369. cross_account:
  370. max_concurrent_assumptions: 10
  371. session_duration_seconds: 7200
  372. ```
  373. ### Docker Deployment
  374. ```dockerfile
  375. FROM python:3.11-slim
  376. WORKDIR /app
  377. COPY . .
  378. RUN pip install -r requirements.txt
  379. EXPOSE 8000
  380. CMD ["python", "aws_security_mcp/main.py", "sse"]
  381. ```
  382. ```bash
  383. docker build -t aws-security-mcp .
  384. docker run -p 8000:8000 \
  385. -e AWS_ACCESS_KEY_ID=your_key \
  386. -e AWS_SECRET_ACCESS_KEY=your_secret \
  387. aws-security-mcp
  388. ```
  389. ### Load Balancer Configuration
  390. - **Health Check**: `GET /health`
  391. - **SSE Endpoint**: `/sse`
  392. - **Timeout**: 60 seconds minimum
  393. - **Sticky Sessions**: Not required
  394. ## Troubleshooting
  395. ### Common Issues
  396. **Tool Discovery Fails**
  397. ```bash
  398. # Check AWS credentials
  399. aws sts get-caller-identity
  400. # Verify cross-account role exists
  401. aws iam get-role --role-name aws-security-mcp-cross-account-access
  402. ```
  403. **Cross-Account Access Denied**
  404. ```bash
  405. # Test role assumption manually
  406. aws sts assume-role \
  407. --role-arn arn:aws:iam::TARGET-ACCOUNT:role/aws-security-mcp-cross-account-access \
  408. --role-session-name test-session
  409. ```
  410. **Performance Issues**
  411. ```yaml
  412. # Reduce concurrent operations
  413. cross_account:
  414. max_concurrent_assumptions: 3
  415. # Enable minimal logging
  416. server:
  417. minimal_logging: true
  418. ```
  419. ### Debug Mode
  420. Enable verbose logging for troubleshooting:
  421. ```bash
  422. export MCP_LOG_LEVEL=debug
  423. export MCP_STARTUP_QUIET=false
  424. python3 aws_security_mcp/main.py sse
  425. ```
  426. ## License
  427. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  428. ## Support
  429. - **Issues**: [GitHub Issues](https://github.com/groovyBugify/aws-security-mcp/issues)
  430. - **Documentation**: [Project Wiki](https://github.com/groovyBugify/aws-security-mcp/wiki)
  431. - **Security Issues**: Please report privately to the maintainers

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.