# aws-mcp-audit (MVP)

A contractor-friendly read-only AWS assessment tool (MCP server) that inventories an AWS environment,
runs deterministic security/ops checks, and generates actionable reports plus a cost/usage snapshot.

## Quick start (uv)
```bash
uv sync
uv run python -m aws_mcp_audit.server
```

## Claude Desktop (Windows) example config
Put this in `%APPDATA%\Claude\claude_desktop_config.json` and adjust the directory path:

```json
{
  "mcpServers": {
    "aws-mcp-audit": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\D_Drive\\Dev\\aws-mcp-audit",
        "run",
        "python",
        "-m",
        "aws_mcp_audit.server"
      ]
    }
  }
}
```

## Tool usage (conceptual)
- `aws_whoami(auth?)`
- `collect_snapshot(scope, auth?) -> snapshot_id`
- `run_checks(snapshot_id) -> finding_set_id`
- `cost_signals(snapshot_id)`
- `cost_explorer_summary(days=30, auth?)` (optional permissions)
- `generate_report(snapshot_id, finding_set_id, format="md|pdf")`

### Auth
All tools accept an optional `auth` object:

```json
{ "mode": "default" }
```

or (contractor-run):

```json
{
  "mode": "assume_role",
  "role_arn": "arn:aws:iam::123456789012:role/ContractorAuditReadOnly",
  "external_id": "client-specific-external-id",
  "session_name": "aws-mcp-audit",
  "region_name": "us-east-1"
}
```

## Outputs
Artifacts are stored locally under `./data/snapshots/<snapshot_id>/`:
- `snapshot.json`
- `findings.json`
- `cost.json` (tier-1 signals)
- `cost_explorer.json` (if enabled)
- `report.md` / `report.pdf`

## Terraform module (client-side)
See `terraform/ContractorAuditReadOnly/` for a simple module that creates a read-only role with ExternalId.