akintunero/mcpshield
GitHub: akintunero/mcpshield
一款基于 MCP 协议的 AI 云安全态势管理工具，能够扫描 AWS 配置错误并自动生成修复方案，同时通过人工审批流程确保修复操作安全可控。
Stars: 0 | Forks: 0
# MCPShield
MCPShield 使用 AI agent 扫描云环境，检测安全配置错误，生成 Terraform 和 CLI 修复方案，并执行 human-in-the-loop 审批工作流。
## 功能
- **21 条云安全规则** — 包含严重、高、中和低级别的发现，并提供 MITRE ATT&CK 和 CIS Benchmark 映射
- **AI 安全分析师** — 集成 Slack 的 agent，负责解释发现结果、确定风险优先级并指导修复
- **Terraform 修复** — 为每个发现自动生成 HCL
- **AWS CLI 修复** — 为每个发现自动生成 CLI 命令
- **Human-in-the-Loop** — 未经明确批准，不执行任何写操作
- **高管报告** — 专业的安全态势评估报告 (Markdown)
- **安全评分** — 0–100 分制，带有 A–F 字母等级和严重程度细分
- **多种 LLM 提供商** — NVIDIA NIM, Gemini, Ollama, 兼容 OpenAI 的平台
- **Web 仪表板** — 实时安全态势可视化
- **云无关架构** — provider 接口已为 AWS, Azure, GCP 等做好准备
## 架构
### 系统拓扑
```
graph TB
%% Styling
classDef user fill:#e0e7ff,stroke:#6366f1,stroke-width:2px,color:#1e1b4b
classDef service fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
classDef engine fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f
classDef cloud fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#064e3b
classDef critical fill:#fee2e2,stroke:#ef4444,stroke-width:3px,color:#7f1d1d,stroke-dasharray: 5 3
subgraph Users[" "]
direction LR
Slack["💬 Slack Bot
Socket Mode"] Browser["🌐 Web Browser
Dashboard UI"] end subgraph Services[" "] direction TB Agent["🤖 AI Security Analyst
LLM + MCP Client"] MCPServer["⚙️ MCP Server
11 Tools · Zod Validation"] API["🔌 REST API Server
Fastify · Port 7802"] end subgraph Engine[" "] direction TB Scanner["🔍 Scanner Engine
21 Security Rules · MITRE + CIS"] Score["📊 Scoring Engine
0–100 Score · A–F Grade"] Generators["📝 Code Generators
Terraform · AWS CLI · Reports"] CloudTools["☁️ AWS SDK Layer
S3 · IAM · EC2 · Lambda · SQS · SNS · SSM · DDB · Secrets"] end subgraph Cloud[" "] Target["🏢 AWS Cloud
API Endpoint"] end Slack -->|"MCP Protocol (SSE)"| MCPServer Browser -->|"HTTP REST"| API Agent -->|"MCP Protocol"| MCPServer API -->|"MCP Client → Server"| MCPServer MCPServer --> Scanner MCPServer --> Score MCPServer --> Generators Scanner --> CloudTools Generators --> CloudTools CloudTools -->|"AWS SDK v3"| Target class Slack,Browser user class Agent,API,MCPServer service class Scanner,Score,Generators,CloudTools engine class Target cloud ``` ### 数据流 ``` sequenceDiagram participant User as 👤 User participant UI as 🖥️ Slack / Dashboard participant MCP as ⚙️ MCP Server participant Engine as 🧠 Security Engine participant Cloud as ☁️ AWS rect rgb(219, 234, 254) Note over User,Cloud: 🔄 SCAN PHASE User->>UI: "scan my environment" UI->>MCP: scan_environment MCP->>Engine: runSecurityEngine() Engine->>Cloud: ListBuckets, ListUsers, ... Cloud-->>Engine: Resource snapshots Engine-->>MCP: 21 rule evaluations MCP->>Engine: computeSecurityScore() Engine-->>MCP: Score + Findings MCP-->>UI: ScanResult (findings + score) UI-->>User: "Found 5 open vulnerabilities" end rect rgb(254, 243, 199) Note over User,Cloud: 📖 EXPLAIN PHASE User->>UI: "explain MCPS-S3-001" UI->>MCP: describe_finding MCP-->>UI: Full details + MITRE/CIS mapping UI-->>User: Business impact + attack scenario end rect rgb(209, 250, 229) Note over User,Cloud: 🛠️ REMEDIATION PHASE User->>UI: "fix finding MCPS-S3-001" UI->>MCP: generate_terraform_fix MCP-->>UI: Terraform HCL code UI-->>User: Show fix + request approval User->>UI: "approve" UI->>MCP: execute_remediation MCP->>Cloud: putPublicAccessBlock, ... Cloud-->>MCP: Success ✅ MCP-->>UI: RemediationResult UI-->>User: "Fix applied, score updated" end ``` ### Human-in-the-Loop 审批工作流 ``` sequenceDiagram participant User as 👤 Slack User participant AI as 🤖 AI Security Analyst participant MCP as ⚙️ MCP Server participant Cloud as ☁️ AWS Note over User,Cloud: 🔍 DISCOVERY User->>AI: @Shield scan environment AI->>MCP: scan_environment MCP-->>AI: Findings + Score AI-->>User: 📋 Report with risk summary Note over User,Cloud: 📄 FIX PROPOSAL User->>AI: @Shield fix MCPS-S3-001 AI->>MCP: generate_terraform_fix MCP-->>AI: Terraform HCL AI-->>User: 🏗️ Proposed fix (HCL block) Note over User,Cloud: ✅ HUMAN APPROVAL User->>AI: @Shield approve AI->>MCP: approve_remediation MCP-->>AI: Approval ID Note over User,Cloud: ⚡ EXECUTION AI->>MCP: execute_remediation MCP->>Cloud: AWS SDK call Cloud-->>MCP: Success MCP-->>AI: Remediation result AI-->>User: ✅ "Remediation complete — score updated" ``` ### Provider 架构 ``` graph LR %% Styling classDef core fill:#1e40af,stroke:#1e3a8a,color:#fff,stroke-width:3px classDef active fill:#059669,stroke:#047857,color:#fff,stroke-width:2px classDef planned fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px,stroke-dasharray: 6 4 classDef sub fill:#d1fae5,stroke:#10b981,color:#064e3b Core["🧩 MCPShield Core"] --> AWS["☁️ AWS Provider"] Core --> Azure["🔵 Azure Provider"] Core --> GCP["🟢 GCP Provider"] Core --> K8s["⎈ Kubernetes Provider"] subgraph Services["AWS Services (Implemented)"] direction TB A1["📦 S3 Scanner
Public access · Encryption · Versioning"] A2["👤 IAM Scanner
Policies · Keys · Password policy"] A3["🖥️ EC2 Scanner
Security groups · Open ports"] A4["⚡ Lambda / CloudTrail
Runtimes · Audit logging"] A5["📨 SQS / SNS / DDB / SSM / Secrets
Encryption · SecureString · KMS"] end AWS --> A1 AWS --> A2 AWS --> A3 AWS --> A4 AWS --> A5 class Core core class AWS active class Azure,GCP,K8s planned class A1,A2,A3,A4,A5 sub ``` 内置 **AWS provider** — Azure, GCP 和 Kubernetes provider 已在路线图中。 ## 技术栈 | 层级 | 技术 | |---|---| | 运行时 | Node.js 22+, TypeScript | | 包管理器 | pnpm workspaces | | MCP SDK | @modelcontextprotocol/sdk | | AI 提供商 | NVIDIA NIM, Gemini, Ollama, 兼容 OpenAI 的平台 | | 云 SDK | AWS SDK v3 | | HTTP | Fastify | | 验证 | Zod | | 日志 | Pino | | Slack | @slack/bolt (Socket Mode) | | 测试 | Vitest | | 代码检查 | ESLint + Prettier | ## 项目结构 ``` mcpshield/ ├── apps/ │ ├── agent/ # Slack bot + LLM integration │ ├── api/ # REST API (dashboard backend) │ ├── dashboard/ # Web dashboard SPA │ └── mcp-server/ # MCP tool server ├── packages/ │ ├── aws-tools/ # AWS SDK clients, scanner, remediator │ ├── security-engine/ # Security rule evaluation (21 rules) │ ├── finding-engine/ # Finding catalog and registry │ ├── scoring-engine/ # Security score calculator (0–100, A–F) │ ├── terraform-generator/ # HCL code generator │ ├── aws-cli-generator/ # CLI command generator │ ├── report-generator/ # Executive report generator │ ├── llm/ # Shared LLM provider adapters │ ├── types/ # Shared Zod schemas and types │ ├── shared/ # Utility functions │ ├── logger/ # Pino logger wrapper │ └── config/ # Environment config loader ├── docs/ # Documentation ├── labs/ # Workshop labs ├── docker/ # Dockerfiles └── docker-compose.yml # Service orchestration ``` ## 快速开始 ### 前置条件 - Node.js >= 22 - pnpm >= 9 - 兼容 AWS 的 endpoint（见下文） ### 设置 ``` # Clone git clone https://github.com/akintunero/mcpshield.git cd mcpshield # 安装依赖 pnpm install # 配置环境 cp .env.example .env # 编辑 .env — 至少设置 LLM_PROVIDER 和你的 API key ``` ### 运行 启动 MCP server 和 API（开启热重载的开发模式）： ``` # Terminal 1 — MCP Server (端口 7801) pnpm --filter @mcpshield/mcp-server dev # Terminal 2 — REST API + Dashboard (端口 7802) pnpm --filter @mcpshield/api dev ``` 或使用 Docker 运行所有服务： ``` docker compose up --build ``` ### 云 Endpoint 通过 `.env` 配置您的 AWS endpoint： ``` LOCALSTACK_ENDPOINT=http://localhost:4566 AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 ``` ## 使用方法 (Slack) ``` @Shield scan environment @Shield show findings @Shield explain finding MCPS-S3-001:vulnerable-bucket @Shield generate terraform finding MCPS-S3-001:vulnerable-bucket @Shield fix finding MCPS-S3-001:vulnerable-bucket @Shield approve @Shield rescan @Shield security score @Shield generate report ``` 或在 `http://localhost:7802` 打开 Web 仪表板。 ## 安全发现（21 条规则） | 严重程度 | 数量 | 示例 | |---|---|---| | 严重 | 3 | 公开的 S3 存储桶、用户具有管理员访问权限、旧的访问密钥 | | 高 | 7 | 对互联网开放的 SSH、对互联网开放的 RDP、缺少加密、无版本控制、禁用 CloudTrail、未加密的 SSM 参数 | | 中 | 8 | 密码策略薄弱、闲置用户、闲置密钥、无存储桶日志记录、Lambda runtime 已弃用、SQS/SNS/DDB/Secrets 缺少加密 | | 低 | 3 | 缺少标签、命名不当、缺少描述 | 每项发现均包含：唯一 ID、严重程度、描述、业务影响、技术影响、攻击场景、最佳实践、MITRE ATT&CK 映射、CIS 映射、Terraform 修复方案、AWS CLI 修复方案以及风险评分。 ## 文档 - [安装指南](docs/installation.md) - [MCP Server 参考](docs/mcp.md) - [AI Agent 指南](docs/agent.md) - [安全引擎](docs/security-engine.md) - [发现引擎](docs/finding-engine.md) - [Slack 集成](docs/slack.md) - [路线图](docs/roadmap.md) ## 贡献 欢迎贡献！请查看[路线图](docs/roadmap.md)了解计划中的功能。请先开启一个 issue 来讨论变更。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)
Socket Mode"] Browser["🌐 Web Browser
Dashboard UI"] end subgraph Services[" "] direction TB Agent["🤖 AI Security Analyst
LLM + MCP Client"] MCPServer["⚙️ MCP Server
11 Tools · Zod Validation"] API["🔌 REST API Server
Fastify · Port 7802"] end subgraph Engine[" "] direction TB Scanner["🔍 Scanner Engine
21 Security Rules · MITRE + CIS"] Score["📊 Scoring Engine
0–100 Score · A–F Grade"] Generators["📝 Code Generators
Terraform · AWS CLI · Reports"] CloudTools["☁️ AWS SDK Layer
S3 · IAM · EC2 · Lambda · SQS · SNS · SSM · DDB · Secrets"] end subgraph Cloud[" "] Target["🏢 AWS Cloud
API Endpoint"] end Slack -->|"MCP Protocol (SSE)"| MCPServer Browser -->|"HTTP REST"| API Agent -->|"MCP Protocol"| MCPServer API -->|"MCP Client → Server"| MCPServer MCPServer --> Scanner MCPServer --> Score MCPServer --> Generators Scanner --> CloudTools Generators --> CloudTools CloudTools -->|"AWS SDK v3"| Target class Slack,Browser user class Agent,API,MCPServer service class Scanner,Score,Generators,CloudTools engine class Target cloud ``` ### 数据流 ``` sequenceDiagram participant User as 👤 User participant UI as 🖥️ Slack / Dashboard participant MCP as ⚙️ MCP Server participant Engine as 🧠 Security Engine participant Cloud as ☁️ AWS rect rgb(219, 234, 254) Note over User,Cloud: 🔄 SCAN PHASE User->>UI: "scan my environment" UI->>MCP: scan_environment MCP->>Engine: runSecurityEngine() Engine->>Cloud: ListBuckets, ListUsers, ... Cloud-->>Engine: Resource snapshots Engine-->>MCP: 21 rule evaluations MCP->>Engine: computeSecurityScore() Engine-->>MCP: Score + Findings MCP-->>UI: ScanResult (findings + score) UI-->>User: "Found 5 open vulnerabilities" end rect rgb(254, 243, 199) Note over User,Cloud: 📖 EXPLAIN PHASE User->>UI: "explain MCPS-S3-001" UI->>MCP: describe_finding MCP-->>UI: Full details + MITRE/CIS mapping UI-->>User: Business impact + attack scenario end rect rgb(209, 250, 229) Note over User,Cloud: 🛠️ REMEDIATION PHASE User->>UI: "fix finding MCPS-S3-001" UI->>MCP: generate_terraform_fix MCP-->>UI: Terraform HCL code UI-->>User: Show fix + request approval User->>UI: "approve" UI->>MCP: execute_remediation MCP->>Cloud: putPublicAccessBlock, ... Cloud-->>MCP: Success ✅ MCP-->>UI: RemediationResult UI-->>User: "Fix applied, score updated" end ``` ### Human-in-the-Loop 审批工作流 ``` sequenceDiagram participant User as 👤 Slack User participant AI as 🤖 AI Security Analyst participant MCP as ⚙️ MCP Server participant Cloud as ☁️ AWS Note over User,Cloud: 🔍 DISCOVERY User->>AI: @Shield scan environment AI->>MCP: scan_environment MCP-->>AI: Findings + Score AI-->>User: 📋 Report with risk summary Note over User,Cloud: 📄 FIX PROPOSAL User->>AI: @Shield fix MCPS-S3-001 AI->>MCP: generate_terraform_fix MCP-->>AI: Terraform HCL AI-->>User: 🏗️ Proposed fix (HCL block) Note over User,Cloud: ✅ HUMAN APPROVAL User->>AI: @Shield approve AI->>MCP: approve_remediation MCP-->>AI: Approval ID Note over User,Cloud: ⚡ EXECUTION AI->>MCP: execute_remediation MCP->>Cloud: AWS SDK call Cloud-->>MCP: Success MCP-->>AI: Remediation result AI-->>User: ✅ "Remediation complete — score updated" ``` ### Provider 架构 ``` graph LR %% Styling classDef core fill:#1e40af,stroke:#1e3a8a,color:#fff,stroke-width:3px classDef active fill:#059669,stroke:#047857,color:#fff,stroke-width:2px classDef planned fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px,stroke-dasharray: 6 4 classDef sub fill:#d1fae5,stroke:#10b981,color:#064e3b Core["🧩 MCPShield Core"] --> AWS["☁️ AWS Provider"] Core --> Azure["🔵 Azure Provider"] Core --> GCP["🟢 GCP Provider"] Core --> K8s["⎈ Kubernetes Provider"] subgraph Services["AWS Services (Implemented)"] direction TB A1["📦 S3 Scanner
Public access · Encryption · Versioning"] A2["👤 IAM Scanner
Policies · Keys · Password policy"] A3["🖥️ EC2 Scanner
Security groups · Open ports"] A4["⚡ Lambda / CloudTrail
Runtimes · Audit logging"] A5["📨 SQS / SNS / DDB / SSM / Secrets
Encryption · SecureString · KMS"] end AWS --> A1 AWS --> A2 AWS --> A3 AWS --> A4 AWS --> A5 class Core core class AWS active class Azure,GCP,K8s planned class A1,A2,A3,A4,A5 sub ``` 内置 **AWS provider** — Azure, GCP 和 Kubernetes provider 已在路线图中。 ## 技术栈 | 层级 | 技术 | |---|---| | 运行时 | Node.js 22+, TypeScript | | 包管理器 | pnpm workspaces | | MCP SDK | @modelcontextprotocol/sdk | | AI 提供商 | NVIDIA NIM, Gemini, Ollama, 兼容 OpenAI 的平台 | | 云 SDK | AWS SDK v3 | | HTTP | Fastify | | 验证 | Zod | | 日志 | Pino | | Slack | @slack/bolt (Socket Mode) | | 测试 | Vitest | | 代码检查 | ESLint + Prettier | ## 项目结构 ``` mcpshield/ ├── apps/ │ ├── agent/ # Slack bot + LLM integration │ ├── api/ # REST API (dashboard backend) │ ├── dashboard/ # Web dashboard SPA │ └── mcp-server/ # MCP tool server ├── packages/ │ ├── aws-tools/ # AWS SDK clients, scanner, remediator │ ├── security-engine/ # Security rule evaluation (21 rules) │ ├── finding-engine/ # Finding catalog and registry │ ├── scoring-engine/ # Security score calculator (0–100, A–F) │ ├── terraform-generator/ # HCL code generator │ ├── aws-cli-generator/ # CLI command generator │ ├── report-generator/ # Executive report generator │ ├── llm/ # Shared LLM provider adapters │ ├── types/ # Shared Zod schemas and types │ ├── shared/ # Utility functions │ ├── logger/ # Pino logger wrapper │ └── config/ # Environment config loader ├── docs/ # Documentation ├── labs/ # Workshop labs ├── docker/ # Dockerfiles └── docker-compose.yml # Service orchestration ``` ## 快速开始 ### 前置条件 - Node.js >= 22 - pnpm >= 9 - 兼容 AWS 的 endpoint（见下文） ### 设置 ``` # Clone git clone https://github.com/akintunero/mcpshield.git cd mcpshield # 安装依赖 pnpm install # 配置环境 cp .env.example .env # 编辑 .env — 至少设置 LLM_PROVIDER 和你的 API key ``` ### 运行 启动 MCP server 和 API（开启热重载的开发模式）： ``` # Terminal 1 — MCP Server (端口 7801) pnpm --filter @mcpshield/mcp-server dev # Terminal 2 — REST API + Dashboard (端口 7802) pnpm --filter @mcpshield/api dev ``` 或使用 Docker 运行所有服务： ``` docker compose up --build ``` ### 云 Endpoint 通过 `.env` 配置您的 AWS endpoint： ``` LOCALSTACK_ENDPOINT=http://localhost:4566 AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 ``` ## 使用方法 (Slack) ``` @Shield scan environment @Shield show findings @Shield explain finding MCPS-S3-001:vulnerable-bucket @Shield generate terraform finding MCPS-S3-001:vulnerable-bucket @Shield fix finding MCPS-S3-001:vulnerable-bucket @Shield approve @Shield rescan @Shield security score @Shield generate report ``` 或在 `http://localhost:7802` 打开 Web 仪表板。 ## 安全发现（21 条规则） | 严重程度 | 数量 | 示例 | |---|---|---| | 严重 | 3 | 公开的 S3 存储桶、用户具有管理员访问权限、旧的访问密钥 | | 高 | 7 | 对互联网开放的 SSH、对互联网开放的 RDP、缺少加密、无版本控制、禁用 CloudTrail、未加密的 SSM 参数 | | 中 | 8 | 密码策略薄弱、闲置用户、闲置密钥、无存储桶日志记录、Lambda runtime 已弃用、SQS/SNS/DDB/Secrets 缺少加密 | | 低 | 3 | 缺少标签、命名不当、缺少描述 | 每项发现均包含：唯一 ID、严重程度、描述、业务影响、技术影响、攻击场景、最佳实践、MITRE ATT&CK 映射、CIS 映射、Terraform 修复方案、AWS CLI 修复方案以及风险评分。 ## 文档 - [安装指南](docs/installation.md) - [MCP Server 参考](docs/mcp.md) - [AI Agent 指南](docs/agent.md) - [安全引擎](docs/security-engine.md) - [发现引擎](docs/finding-engine.md) - [Slack 集成](docs/slack.md) - [路线图](docs/roadmap.md) ## 贡献 欢迎贡献！请查看[路线图](docs/roadmap.md)了解计划中的功能。请先开启一个 issue 来讨论变更。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)
标签：AWS, DPI, ECS, MITM代理, Terraform, 云安全态势管理, 人工智能, 前端应用, 模型上下文协议, 漏洞修复, 用户模式Hook绕过, 网络安全培训, 自动化攻击, 请求拦截