内容
# MCP dAWShund 服务器
此软件包将 [dAWShund 项目](https://github.com/FalconForceTeam/dAWShund) 封装在两个不同的服务器中，
以便您可以枚举 AWS IAM 数据、评估有效权限并获得高级别的摘要，
而无需记住一系列单独的脚本。 上游项目描述了自己是一种方法，
“给顽皮的权限套上牵绳”，并提供三个主要组件：
* **sAWSage** – 枚举 IAM 主要元素和资源策略，并将它们合并为单个 JSON 文档。 支持的资源包括 IAM 组、角色和用户，
以及部分基于资源的策略，例如 AWS Backup、EFS、KMS、Lambda、S3、SNS 和 SQS。 合并文件 (`sawsage.json`) 在运行脚本后生成于 `policies/` 目录下。
* **Gerakina** – 将合并的策略输入 AWS 的 `simulate-principal-policy` API，并生成一个新的 JSON 文件，
`effective_permissions.json`，列出每个主要元素的允许、显式拒绝或隐式拒绝的操作。 此步骤可能需要一些时间，
因为它为每个主要元素、操作和资源的唯一组合调用 AWS API。
* **dAWShund** – 将有效权限导入 Neo4j 数据库，并构建主要元素和资源的图。 它生成 `permissions4j.json` 和 `dawshund.json`，
适用于在 Neo4j 和 BloodHound 中浏览。 使用 Neo4j 功能是可选的；此处包含的 HTTP 服务器提供了一个轻量级摘要。
## 需求
dAWShund 依赖于 Python、AWS CLI 和一些 Python 包。 如果您想使用 Neo4j 可视化，还需要一个正在运行的 Neo4j 实例。
至少需要：
* Python 3.x
* 具有调用 IAM API 的权限的 AWS 账户（用于枚举）和 `simulate-principal-policy` API（用于评估）。 您应该使用 `aws configure --profile <profile_name>` 配置您的 AWS 凭证。
* 已安装并可在您的路径上使用的 AWS CLI。
* **可选：** 如果您计划直接使用 `dawshund.py` 脚本，则需要一个 Neo4j 服务器（HTTP 服务器在没有 Neo4j 的情况下总结结果）。
此目录中的 `setup.sh` 脚本将安装 Python 依赖项（使用 `pip`）并克隆上游 dAWShund 仓库。
如果您更喜欢手动管理依赖项，可以查看 `setup.sh` 以获取确切的命令。
## 安装
1. 安装 AWS CLI 并为要评估的账户配置一个命名配置文件。例如：
```bash
# 通过包管理器或从 https://aws.amazon.com/cli/ 安装 AWS CLI
aws configure --profile myprofile
```
2. 克隆此仓库（或复制 `mcp_dawshund_server` 文件夹）并运行设置脚本：
```bash
cd mcp_dawshund_server
./setup.sh
```
脚本安装 Python 依赖项（`boto3`、`neo4j`、`flask`、`flask_cors`）并将 dAWShund 代码克隆到本地子目录中。
如果您希望使用 Python 虚拟环境，可以在运行 `setup.sh` 之前创建并激活它。
3. 启动服务器：
```bash
python3 server.py
```
默认情况下，HTTP 服务监听所有接口上的 8000 端口。 您可以通过在启动服务器前设置 `PORT` 环境变量来更改端口，
例如：
```bash
PORT=5000 python3 server.py
```
如果您打算使用 MCP 实现而不是 HTTP API，可以运行：
```bash
python3 iam_mcp_server.py
```
MCP 服务器不绑定到 TCP 端口；它通过标准输入/输出进行通信，通常由 Claude for Desktop 等客户端启动。
有关详细信息，请参见下面的 [使用 MCP 服务器](#使用MCP服务器)。
## 使用 HTTP 服务器
基于 Flask 的服务器 (`server.py`) 通过 HTTP 公开三个端点。 所有请求和响应都使用 JSON。
以下示例使用 `curl`，但任何 HTTP 客户端都可以使用。
### 1 – 枚举 IAM 策略（`/collect`）
通过 sAWSage 触发 IAM 主要元素和资源策略的枚举。 提供您的 AWS CLI 配置文件名称和可选的区域数组。
如果未提供区域，sAWSage 将枚举支持的服务的所有已知区域。
```bash
curl -X POST http://localhost:8000/collect \
-H 'Content-Type: application/json' \
-d '{"profile": "myprofile", "regions": ["us-west-2", "us-east-1"]}'
```
响应是一个大型 JSON 文档，按 AWS ARN 键控。 每个条目都包含元数据（友好名称、附加策略）和从内联和托管策略中提取的原始语句。
相同的文件保存为 `dAWShund/policies/sawsage.json` 以备后用。
### 2 – 评估有效权限（`/evaluate`）
使用 AWS `simulate-principal-policy` API 模拟附加到每个主要元素的权限。 此端点只需要您的配置文件名称：
```bash
curl -X POST http://localhost:8000/evaluate \
-H 'Content-Type: application/json' \
-d '{"profile": "myprofile"}'
```
响应包含 `effective_permissions.json` 的内容 – 一个按主要元素 ARN 键控的字典。 在每个条目中，
`Permissions` 键包含名为 `allowed`、`explicitDeny` 和 `implicitDeny` 的列表，
它们列出了该主要元素的操作（action，resource）元组。
### 3 – 总结评估（`/analyze`）
检索评估的紧凑摘要。 此端点读取 `effective_permissions.json` 并计算每个主要元素允许、显式拒绝和隐式拒绝的操作数量。
不需要请求正文：
```bash
curl -X POST http://localhost:8000/analyze -H 'Content-Type: application/json' -d '{}'
```
响应如下所示（示例）：
```json
{
"arn:aws:iam::123456789012:user/Alice": {
"allowed": 42,
"explicitDeny": 0,
"implicitDeny": 5
},
"arn:aws:iam::123456789012:role/AdminRole": {
"allowed": 128,
"explicitDeny": 0,
"implicitDeny": 0
}
}
```
此摘要可以帮助您快速识别具有过多权限的主要元素或具有意外隐式拒绝的主要元素。
对于更深入的分析，您可以连接到 Neo4j 数据库并运行原始的 `dawshund.py` 脚本，
该脚本将构建一个图并创建 `permissions4j.json` 和 `dawshund.json`。
## 使用 MCP 服务器
除了基于 Flask 的 HTTP API 外，此软件包还包含一个使用 `fastmcp` 库实现的 **Model Context Protocol (MCP) 服务器**。
MCP 服务器通过 JSON-RPC 进行通信，旨在被 Claude Desktop 等 AI 助手或自定义 FastMCP 客户端使用。
MCP 服务器公开的操作与 HTTP API 相同，但使用结构化的工具定义代替 HTTP 端点。
### 1 – 安装 FastMCP
提供的 `setup.sh` 脚本为您安装 `fastmcp` 包。 如果您手动管理依赖项，请使用以下命令安装：
```bash
pip install fastmcp
```
FastMCP 需要 Python 3.10 或更高版本。
### 2 – 手动运行服务器
要在本地测试 MCP 服务器，请运行：
```bash
python3 iam_mcp_server.py
```
这将启动服务器在标准输入上。 您可以运行：
```bash
fastmcp run iam_mcp_server.py:mcp --transport http --port 8000
```
### 3 – 可用工具
MCP 服务器公开三个工具。 每个工具都返回结构化的 JSON 内容，并附有简要摘要：
| 工具名称 | 描述 | 输入参数 |
|---------------|---------------------------------------------------------------|---------------------------------------------------------------------|
| `collect_iam` | 使用 sAWSage 枚举 IAM 主要元素和资源策略 | `profile`（字符串，必填），`regions`（字符串数组，可选） |
| `evaluate_iam`| 使用 Gerakina 模拟有效权限 | `profile`（字符串，必填） |
| `analyze_iam` | 总结每个主要元素的允许、显式和隐式拒绝 | 无 |
**collect** 和 **evaluate** 工具返回一条短消息和其各自 JSON 输出文件的路径（完整文档可能有几百千字节）。
**analyze** 工具读取有效权限文件并返回一个按主要元素 ARN 键控的字典，其中包含允许和拒绝操作的数量。
### 4 – 与 Claude Desktop 集成
Claude Desktop 可以在 `claude_desktop_config.json` 文件中启动本地 MCP 服务器。
在 macOS 上，该文件位于 `~/Library/Application Support/Claude/claude_desktop_config.json`。
在 `mcpServers` 键下添加一个新条目：
```json
{
"mcpServers": {
"iam-analysis": {
"command": "/usr/bin/python3",
"args": [
"/ABSOLUTE/PATH/TO/iam_mcp_server.py"
]
}
}
}
```
将路径替换为系统上的正确位置。 保存文件后 **重启 Claude Desktop**；
配置仅在启动时读取。 当您的自然语言提示需要 IAM 枚举或权限模拟时，
Claude 将调用相应的工具。 例如，您可以说：
> “枚举我的默认配置文件的 IAM 策略，并总结允许或拒绝的操作数量。”
Claude 将发出 `collect_iam` 调用，接着是 `evaluate_iam` 和 `analyze_iam`。
每个工具的结果将返回给 Claude，并纳入助手的最终响应中。
或者，您可以通过运行以下命令使 MCP 服务器作为 **远程连接器**：
```bash
fastmcp run iam_mcp_server.py:mcp --transport http --port 8000
```
并在 Claude 的设置中注册 URL。 例如，启动服务器：
```bash
fastmcp run iam_mcp_server.py:mcp --transport http --port 8000
```
然后在 Claude 的设置中添加 `http://localhost:8000/mcp` 作为自定义连接器。
## 注意事项和限制
* **所需的权限：** 枚举步骤使用 IAM API，例如 `list_users`、`list_roles` 和 `get_user_policy`。
评估步骤调用 `simulate-principal-policy`，它反过来评估操作与资源。
确保您使用的 AWS 配置文件具有执行这些操作的足够权限。
* **运行时和成本：** 策略模拟可能需要一些时间，因为它为每个主要元素/操作/资源组合调用一个 API 调用。
对于具有许多主要元素和策略的账户，这可能需要几分钟。 模拟 API 本身没有额外的 AWS 成本，
但枚举查询会受到正常的 API 速率限制。
* **Neo4j 集成：** 默认情况下，`dawshund.py` 连接到 `localhost:7687` 上的 Neo4j 实例，用户名为 `neo4j`，密码为 `dawshund`。
如果您希望填充您自己的 Neo4j 数据库，请在运行 `dAWShund/dawshund.py` 之前编辑 `NEO4J_URI` 和 `NEO4J_AUTH` 值。
此处提供的 HTTP 服务器根本不使用 Neo4j；而是总结 JSON 输出。
* **可扩展性：** 上游项目目前枚举有限一组服务的资源策略。
如果您需要覆盖其他服务，请考虑为上游存储库贡献服务枚举器。
## 许可证
此软件包捆绑了 dAWShund 脚本，这些脚本在 BSD 3-Clause 许可证下获得许可。
有关详细信息，请参见上游存储库。
此文件夹中的包装代码（服务器和设置脚本）被释放到公共领域。
您可以随意使用它们。
