# MCP dAWShund Server

This package wraps the [dAWShund project](https://github.com/FalconForceTeam/dAWShund) 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:

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

2. Clone this repository (or copy the `mcp_dawshund_server` folder)
   and run the setup script:

   ```bash
   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`.

3. Start the server:

   ```bash
   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:

   ```bash
   PORT=5000 python3 server.py
   ```

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

   ```bash
   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](#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.

```bash
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:

```bash
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:

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

The response looks like this (example):

```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
  }
}
```

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:

```bash
pip install fastmcp
```

FastMCP requires Python 3.10 or later.

### 2 – Run the server manually

To test the MCP server locally, run:

```bash
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:

```bash
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:

```json
{
  "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

```bash
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.