MCP dAWShund Server

1# MCP dAWShund Server
2 
3This package wraps the [dAWShund project](https://github.com/FalconForceTeam/dAWShund) in two different servers
4so you can enumerate AWS IAM data, evaluate effective permissions and
5obtain a high‑level summary without having to remember a handful of
6separate scripts.  The upstream project describes itself as a way to
7“put a leash on naughty permissions” and provides three main
8components:
9 
10* **sAWSage** – enumerates IAM principals and resource policies and
11  consolidates them into a single JSON document.  Supported resources
12  include IAM groups, roles and users and a subset of resource based
13  policies such as AWS Backup, EFS, KMS, Lambda, S3, SNS and SQS.  The
14  consolidated file (`sawsage.json`) is produced under `policies/`
15  after running the scrip.
16* **Gerakina** – feeds the consolidated policies into AWS’s
17  `simulate-principal-policy` API and produces a new JSON file,
18  `effective_permissions.json`, listing which actions are allowed,
19  explicitly denied or implicitly denied for each principal.  This
20  step may take some time because it calls the AWS API for every
21  unique combination of principal, action and resource.
22* **dAWShund** – imports the effective permissions into a Neo4j
23  database and builds a graph of principals and resources.  It
24  generates `permissions4j.json` and `dawshund.json` suitable for
25  browsing in Neo4j and BloodHound respectively.  Using the Neo4j
26  functionality is optional; the HTTP server included here provides a
27  lightweight summary instead.
28 
29## Requirements
30 
31dAWShund depends on Python, the AWS CLI and a handful of Python
32packages.  If you wish to use the Neo4j visualisation then a
33running Neo4j instance is also required.  At a minimum you need:
34 
35* Python 3.x
36* An AWS account with permissions to call IAM APIs (for enumeration)
37  and the `simulate-principal-policy` API (for evaluation).  You
38  should configure your AWS credentials using `aws configure --profile
39  <profile_name>`.
40* The AWS CLI installed and available on your path.
41* **Optional:** a Neo4j server if you plan to use the `dawshund.py`
42  script directly (the HTTP server summarises results without Neo4j).
43 
44The `setup.sh` script in this directory will install Python
45dependencies (using `pip`) and clone the upstream dAWShund repository.
46If you prefer to manage dependencies manually you can see
47`setup.sh` for the exact commands.
48 
49## Installation
50 
511. Install the AWS CLI and configure a named profile for the account
52   you wish to assess.  For example:
53 
54   ```bash
55   # install the AWS CLI via your package manager or from https://aws.amazon.com/cli/
56   aws configure --profile myprofile
57   ```
58 
592. Clone this repository (or copy the `mcp_dawshund_server` folder)
60   and run the setup script:
61 
62   ```bash
63   cd mcp_dawshund_server
64   ./setup.sh
65   ```
66 
67   The script installs Python dependencies (`boto3`, `neo4j`, `flask`,
68   `flask_cors`) and clones the dAWShund code into a local
69   subdirectory.  If you wish to use a Python virtual environment you
70   can create and activate one before running `setup.sh`.
71 
723. Start the server:
73 
74   ```bash
75   python3 server.py
76   ```
77 
78   By default the HTTP service listens on port 8000 on all interfaces.
79   You can change the port by setting the `PORT` environment variable
80   before starting the server, for example:
81 
82   ```bash
83   PORT=5000 python3 server.py
84   ```
85 
86   If you intend to use the MCP implementation instead of the HTTP API,
87   you can run it with:
88 
89   ```bash
90   python3 iam_mcp_server.py
91   ```
92 
93   The MCP server does not bind to a TCP port; it communicates via
94   standard input/output and is typically launched by a client such as
95   Claude for Desktop.  See [Using the MCP server](#using-the-mcp-server)
96   below for details.
97 
98## Using the HTTP server
99 
100The Flask-based server (`server.py`) exposes three endpoints over HTTP.
101All requests and responses use JSON.  The examples below use `curl`
102but any HTTP client will work.
103 
104### 1 – Enumerate IAM policies (`/collect`)
105 
106Trigger enumeration of IAM principals and resource policies via
107sAWSage.  Provide your AWS CLI profile name and optionally an array of
108regions.  If no regions are supplied, sAWSage enumerates all known
109regions for supported services.
110 
111```bash
112curl -X POST http://localhost:8000/collect \
113     -H 'Content-Type: application/json' \
114     -d '{"profile": "myprofile", "regions": ["us-west-2", "us-east-1"]}'
115```
116 
117The response is a large JSON document keyed by AWS ARN.  Each entry
118includes metadata (friendly name, attached policies) and the raw
119statements extracted from inline and managed policies.  The same file
120is saved to `dAWShund/policies/sawsage.json` for later use.
121 
122### 2 – Evaluate effective permissions (`/evaluate`)
123 
124Simulate the permissions attached to each principal using the AWS
125`simulate-principal-policy` API.  This endpoint requires only your
126profile name:
127 
128```bash
129curl -X POST http://localhost:8000/evaluate \
130     -H 'Content-Type: application/json' \
131     -d '{"profile": "myprofile"}'
132```
133 
134The response contains the contents of
135`effective_permissions.json` – a dictionary keyed by principal ARN.
136Within each entry the `Permissions` key contains lists named
137`allowed`, `explicitDeny` and `implicitDeny` listing the (action,
138resource) tuples for that principal.
139 
140### 3 – Summarise the evaluation (`/analyze`)
141 
142Retrieve a compact summary of the evaluation.  This endpoint reads
143`effective_permissions.json` and counts how many actions are allowed,
144explicitly denied and implicitly denied for each principal.  No
145request body is required:
146 
147```bash
148curl -X POST http://localhost:8000/analyze -H 'Content-Type: application/json' -d '{}'
149```
150 
151The response looks like this (example):
152 
153```json
154{
155  "arn:aws:iam::123456789012:user/Alice": {
156    "allowed": 42,
157    "explicitDeny": 0,
158    "implicitDeny": 5
159  },
160  "arn:aws:iam::123456789012:role/AdminRole": {
161    "allowed": 128,
162    "explicitDeny": 0,
163    "implicitDeny": 0
164  }
165}
166```
167 
168This summary can help you quickly identify over‑privileged principals or
169those with unexpected implicit denies.  For deeper analysis you can
170connect to a Neo4j database and run the original `dawshund.py`
171script, which will build a graph and create `permissions4j.json` and
172`dawshund.json`.
173 
174## Using the MCP server
175 
176In addition to the Flask HTTP API, this package includes a **Model
177Context Protocol (MCP) server** implemented with the `fastmcp`
178library. MCP servers communicate over JSON‑RPC and are designed to be
179consumed by AI assistants like Claude Desktop or custom FastMCP clients
180.  The MCP server exposes the same operations as the
181HTTP API but uses structured tool definitions instead of HTTP
182endpoints.
183 
184### 1 – Install FastMCP
185 
186The provided `setup.sh` script installs the `fastmcp` package for you.
187If you are managing dependencies manually, install it with:
188 
189```bash
190pip install fastmcp
191```
192 
193FastMCP requires Python 3.10 or later.
194 
195### 2 – Run the server manually
196 
197To test the MCP server locally, run:
198 
199```bash
200python3 iam_mcp_server.py
201```
202 
203This launches the server in STDIO mode.  It will block and listen for
204JSON‑RPC requests on standard input.  You can also run the server over
205HTTP if you plan to expose it as a remote connector:
206 
207```bash
208fastmcp run iam_mcp_server.py:mcp --transport http --port 8000
209```
210 
211### 3 – Available tools
212 
213The MCP server exposes three tools.  Each tool returns JSON structured
214content and is accompanied by a brief summary:
215 
216| Tool name      | Description                                                   | Input parameters                                                    |
217|---------------|---------------------------------------------------------------|---------------------------------------------------------------------|
218| `collect_iam` | Enumerate IAM principals and resource policies using sAWSage  | `profile` (string, required), `regions` (array of strings, optional) |
219| `evaluate_iam`| Simulate effective permissions using Gerakina                | `profile` (string, required)                                        |
220| `analyze_iam` | Summarise allowed, explicit and implicit denies per principal | None                                                                |
221 
222The **collect** and **evaluate** tools return a short message and the
223path to their respective JSON output files (the full documents can be
224hundreds of kilobytes).  The **analyze** tool reads the effective
225permissions file and returns a dictionary keyed by principal ARN with
226counts of allowed and denied actions.
227 
228### 4 – Integrate with Claude Desktop
229 
230Claude Desktop can launch local MCP servers defined in a
231`claude_desktop_config.json` file.  On macOS this file resides at
232`~/Library/Application Support/Claude/claude_desktop_config.json`
233.  Add a new entry under the `mcpServers` key:
234 
235```json
236{
237  "mcpServers": {
238    "iam-analysis": {
239      "command": "/usr/bin/python3",
240      "args": [
241        "/ABSOLUTE/PATH/TO/iam_mcp_server.py"
242      ]
243    }
244  }
245}
246```
247 
248Replace the paths with the correct locations on your system.  After
249saving the file **restart Claude Desktop**; the configuration is read
250only on startup.  When your natural language prompt
251requires IAM enumeration or permission simulation, Claude will call the
252appropriate tool.  For example, you might say:
253 
254> “Enumerate IAM policies for my default profile and summarise how many
255> actions are allowed or denied.”
256 
257Claude will issue a `collect_iam` call, followed by `evaluate_iam` and
258finally `analyze_iam`.  The results from each tool will be returned
259back to Claude and incorporated into the assistant’s final response.
260 
261Alternatively, you can expose the MCP server as a **remote connector**
262by running it over HTTP and registering the URL in Claude’s web
263interface.  For example, start the server via
264 
265```bash
266fastmcp run iam_mcp_server.py:mcp --transport http --port 8000
267```
268 
269and then add `http://localhost:8000/mcp` as a custom connector in
270Claude’s settings.
271 
272## Notes and caveats
273 
274* **Permissions required:** The enumeration step uses IAM APIs such
275  as `list_users`, `list_roles` and `get_user_policy`.  The
276  evaluation step calls `simulate-principal-policy`, which in turn
277  evaluates actions against resources.  Make sure the AWS profile you
278  use has sufficient permissions to perform these operations.
279* **Runtime and cost:** Simulating policies can be time consuming
280  because it makes one API call per principal/action/resource
281  combination.  For accounts with many principals and policies this
282  may take several minutes.  There is no additional AWS cost for the
283  simulation API itself, but the enumeration queries are subject to
284  normal API rate limits.
285* **Neo4j integration:** By default `dawshund.py` connects to a
286  Neo4j instance running on `localhost:7687` with username `neo4j`
287  and password `dawshund`.  If you wish to populate your own Neo4j
288  database, edit the `NEO4J_URI` and `NEO4J_AUTH` values in
289  `dAWShund/dawshund.py` before running it.  The HTTP server
290  provided here does not use Neo4j at all; instead it summarises
291  the JSON output.
292* **Extensibility:** The upstream project currently enumerates
293  resource policies for a limited set of services.  If you
294  need coverage for additional services, consider contributing a
295  service enumerator to the upstream repository.
296 
297## License
298 
299This package bundles the dAWShund scripts, which are licensed under
300the BSD 3‑Clause license.  See the upstream repository for
301details.  The wrapper code in this folder (the server and setup
302scripts) is released into the public domain.  Use them however you
303like.