dawshund_mcp

MCP dAWShund Server

This package wraps the dAWShund project in two different servers so you can enumerate AWS IAM data, evaluate effective permissions and obtain a high‑level summary without having to remember a handful of separate scripts. The upstream project describes itself as a way to “put a leash on naughty permissions” and provides three main components:

• sAWSage – enumerates IAM principals and resource policies and

consolidates them into a single JSON document. Supported resources include IAM groups, roles and users and a subset of resource based policies such as AWS Backup, EFS, KMS, Lambda, S3, SNS and SQS. The consolidated file (sawsage.json) is produced under policies/ after running the scrip.

• Gerakina – feeds the consolidated policies into AWS’s

simulate-principal-policy API and produces a new JSON file, effective_permissions.json, listing which actions are allowed, explicitly denied or implicitly denied for each principal. This step may take some time because it calls the AWS API for every unique combination of principal, action and resource.

• dAWShund – imports the effective permissions into a Neo4j

database and builds a graph of principals and resources. It generates permissions4j.json and dawshund.json suitable for browsing in Neo4j and BloodHound respectively. Using the Neo4j functionality is optional; the HTTP server included here provides a lightweight summary instead.

Requirements

dAWShund depends on Python, the AWS CLI and a handful of Python packages. If you wish to use the Neo4j visualisation then a running Neo4j instance is also required. At a minimum you need:

• Python 3.x
• An AWS account with permissions to call IAM APIs (for enumeration)

and the simulate-principal-policy API (for evaluation). You should configure your AWS credentials using aws configure --profile <profile_name>.

• The AWS CLI installed and available on your path.
• Optional: a Neo4j server if you plan to use the dawshund.py

script directly (the HTTP server summarises results without Neo4j).

The setup.sh script in this directory will install Python dependencies (using pip) and clone the upstream dAWShund repository. If you prefer to manage dependencies manually you can see setup.sh for the exact commands.

Installation

1. Install the AWS CLI and configure a named profile for the account

you wish to assess. For example:

   # install the AWS CLI via your package manager or from https://aws.amazon.com/cli/
   aws configure --profile myprofile

1. Clone this repository (or copy the mcp_dawshund_server folder)

and run the setup script:

   cd mcp_dawshund_server
   ./setup.sh

The script installs Python dependencies (boto3, neo4j, flask, flask_cors) and clones the dAWShund code into a local subdirectory. If you wish to use a Python virtual environment you can create and activate one before running setup.sh.

1. Start the server:

   python3 server.py

By default the HTTP service listens on port 8000 on all interfaces. You can change the port by setting the PORT environment variable before starting the server, for example:

   PORT=5000 python3 server.py

If you intend to use the MCP implementation instead of the HTTP API, you can run it with:

   python3 iam_mcp_server.py

The MCP server does not bind to a TCP port; it communicates via standard input/output and is typically launched by a client such as Claude for Desktop. See Using the MCP server below for details.

Using the HTTP server

The Flask-based server (server.py) exposes three endpoints over HTTP. All requests and responses use JSON. The examples below use curl but any HTTP client will work.

1 – Enumerate IAM policies (/collect)

Trigger enumeration of IAM principals and resource policies via sAWSage. Provide your AWS CLI profile name and optionally an array of regions. If no regions are supplied, sAWSage enumerates all known regions for supported services.

curl -X POST http://localhost:8000/collect \
     -H 'Content-Type: application/json' \
     -d '{"profile": "myprofile", "regions": ["us-west-2", "us-east-1"]}'

The response is a large JSON document keyed by AWS ARN. Each entry includes metadata (friendly name, attached policies) and the raw statements extracted from inline and managed policies. The same file is saved to dAWShund/policies/sawsage.json for later use.

2 – Evaluate effective permissions (/evaluate)

Simulate the permissions attached to each principal using the AWS simulate-principal-policy API. This endpoint requires only your profile name:

curl -X POST http://localhost:8000/evaluate \
     -H 'Content-Type: application/json' \
     -d '{"profile": "myprofile"}'

The response contains the contents of effective_permissions.json – a dictionary keyed by principal ARN. Within each entry the Permissions key contains lists named allowed, explicitDeny and implicitDeny listing the (action, resource) tuples for that principal.

3 – Summarise the evaluation (/analyze)

Retrieve a compact summary of the evaluation. This endpoint reads effective_permissions.json and counts how many actions are allowed, explicitly denied and implicitly denied for each principal. No request body is required:

curl -X POST http://localhost:8000/analyze -H 'Content-Type: application/json' -d '{}'

The response looks like this (example):

{
  "arn:aws:iam::123456789012:user/Alice": {
    "allowed": 42,
    "explicitDeny": 0,
    "implicitDeny": 5
  },
  "arn:aws:iam::123456789012:role/AdminRole": {
    "allowed": 128,
    "explicitDeny": 0,
    "implicitDeny": 0
  }
}

This summary can help you quickly identify over‑privileged principals or those with unexpected implicit denies. For deeper analysis you can connect to a Neo4j database and run the original dawshund.py script, which will build a graph and create permissions4j.json and dawshund.json.

Using the MCP server

In addition to the Flask HTTP API, this package includes a Model Context Protocol (MCP) server implemented with the fastmcp library. MCP servers communicate over JSON‑RPC and are designed to be consumed by AI assistants like Claude Desktop or custom FastMCP clients . The MCP server exposes the same operations as the HTTP API but uses structured tool definitions instead of HTTP endpoints.

1 – Install FastMCP

The provided setup.sh script installs the fastmcp package for you. If you are managing dependencies manually, install it with:

pip install fastmcp

FastMCP requires Python 3.10 or later.

2 – Run the server manually

To test the MCP server locally, run:

python3 iam_mcp_server.py

This launches the server in STDIO mode. It will block and listen for JSON‑RPC requests on standard input. You can also run the server over HTTP if you plan to expose it as a remote connector:

fastmcp run iam_mcp_server.py:mcp --transport http --port 8000

3 – Available tools

The MCP server exposes three tools. Each tool returns JSON structured content and is accompanied by a brief summary:

| Tool name | Description | Input parameters | |---------------|---------------------------------------------------------------|---------------------------------------------------------------------| | collect_iam | Enumerate IAM principals and resource policies using sAWSage | profile (string, required), regions (array of strings, optional) | | evaluate_iam| Simulate effective permissions using Gerakina | profile (string, required) | | analyze_iam | Summarise allowed, explicit and implicit denies per principal | None |

The collect and evaluate tools return a short message and the path to their respective JSON output files (the full documents can be hundreds of kilobytes). The analyze tool reads the effective permissions file and returns a dictionary keyed by principal ARN with counts of allowed and denied actions.

4 – Integrate with Claude Desktop

Claude Desktop can launch local MCP servers defined in a claude_desktop_config.json file. On macOS this file resides at ~/Library/Application Support/Claude/claude_desktop_config.json . Add a new entry under the mcpServers key:

{
  "mcpServers": {
    "iam-analysis": {
      "command": "/usr/bin/python3",
      "args": [
        "/ABSOLUTE/PATH/TO/iam_mcp_server.py"
      ]
    }
  }
}

Replace the paths with the correct locations on your system. After saving the file restart Claude Desktop; the configuration is read only on startup. When your natural language prompt requires IAM enumeration or permission simulation, Claude will call the appropriate tool. For example, you might say:

“Enumerate IAM policies for my default profile and summarise how many actions are allowed or denied.”

Claude will issue a collect_iam call, followed by evaluate_iam and finally analyze_iam. The results from each tool will be returned back to Claude and incorporated into the assistant’s final response.

Alternatively, you can expose the MCP server as a remote connector by running it over HTTP and registering the URL in Claude’s web interface. For example, start the server via

fastmcp run iam_mcp_server.py:mcp --transport http --port 8000

and then add http://localhost:8000/mcp as a custom connector in Claude’s settings.

Notes and caveats

• Permissions required: The enumeration step uses IAM APIs such

as list_users, list_roles and get_user_policy. The evaluation step calls simulate-principal-policy, which in turn evaluates actions against resources. Make sure the AWS profile you use has sufficient permissions to perform these operations.

• Runtime and cost: Simulating policies can be time consuming

because it makes one API call per principal/action/resource combination. For accounts with many principals and policies this may take several minutes. There is no additional AWS cost for the simulation API itself, but the enumeration queries are subject to normal API rate limits.

• Neo4j integration: By default dawshund.py connects to a

Neo4j instance running on localhost:7687 with username neo4j and password dawshund. If you wish to populate your own Neo4j database, edit the NEO4J_URI and NEO4J_AUTH values in dAWShund/dawshund.py before running it. The HTTP server provided here does not use Neo4j at all; instead it summarises the JSON output.

• Extensibility: The upstream project currently enumerates

resource policies for a limited set of services. If you need coverage for additional services, consider contributing a service enumerator to the upstream repository.

License

This package bundles the dAWShund scripts, which are licensed under the BSD 3‑Clause license. See the upstream repository for details. The wrapper code in this folder (the server and setup scripts) is released into the public domain. Use them however you like.