# duo-labs/cloudmapper architecture

> Architecture diagram of the GitHub repository duo-labs/cloudmapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/duo-labs/cloudmapper
- Repository: https://github.com/duo-labs/cloudmapper

## Overview

CloudMapper is an AWS environment analysis tool. Its main workflow collects account metadata, stores it as JSON, then runs analysis commands that produce findings, reports, and resource views. The README documents additional IAM, exposure, unused-resource, statistics, and trust-analysis capabilities. Network visualization is explicitly no longer maintained. The graph includes the separate CloudMapper Auditor deployment; unsampled command implementations are represented by their exact paths, with documented capabilities and evidence limits noted rather than assumed call chains.

Main entry points: [`cloudmapper.py`](https://github.com/duo-labs/cloudmapper/blob/main/cloudmapper.py) (Command dispatcher), [`commands/report.py`](https://github.com/duo-labs/cloudmapper/blob/main/commands/report.py) (Account report), [`commands/collect.py`](https://github.com/duo-labs/cloudmapper/blob/main/commands/collect.py) (AWS metadata collection), [`shared/audit.py`](https://github.com/duo-labs/cloudmapper/blob/main/shared/audit.py) (Audit rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and collection"]
  node_cli["Command dispatcher<br/>[cloudmapper.py]"]
  node_collect["AWS metadata collection<br/>[collect.py]"]
  node_dataset[("Account JSON data")]
  node_query["Collected-data reader<br/>[query.py]"]
end

subgraph group_analysis["Security analysis"]
  node_auditcmd["Misconfiguration audit<br/>[audit.py]"]
  node_auditengine["Audit rules<br/>[audit.py]"]
  node_iamaudit["IAM policy analysis<br/>[iam_audit.py]"]
  node_admins["Admin discovery<br/>[find_admins.py]"]
  node_public["Public exposure scan<br/>[public.py]"]
  node_unused["Unused resource scan<br/>[find_unused.py]"]
  node_common["Shared analysis utilities<br/>[common.py]"]
end

subgraph group_reporting["Reports and mapping"]
  node_report["Account report<br/>[report.py]"]
  node_iamreport["IAM report<br/>[iam_report.py]"]
  node_prepare["Network preparation<br/>[prepare.py]"]
  node_webserver["Local web server<br/>[webserver.py]"]
  node_webmap["Network map UI<br/>[cloudmap.js]"]
  node_nodes["AWS resource model<br/>[nodes.py]"]
end

subgraph group_support["Account insights"]
  node_stats["Resource statistics<br/>[stats.py]"]
  node_sgips["Security-group IPs<br/>[sg_ips.py]"]
  node_trust["Web of trust<br/>[weboftrust.py]"]
  node_organization["Organization discovery<br/>[organization.py]"]
end

subgraph group_auditor["CloudMapper Auditor"]
  node_auditorstack["Auditor infrastructure"]
  node_auditorlambda["Alarm forwarder<br/>[main.py]"]
end

node_operator(("Operator"))
node_aws{{"AWS account"}}

node_operator -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_collect
node_operator -->|"requests collection"| node_collect
node_collect -->|"reads metadata"| node_aws
node_collect -->|"records JSON"| node_dataset
node_dataset -->|"loads data"| node_query
node_cli -->|"dispatches to"| node_auditcmd
node_auditcmd -->|"runs checks"| node_auditengine
node_auditengine -->|"reads collected data"| node_query
node_auditengine -->|"uses IAM checks"| node_iamaudit
node_cli -->|"dispatches to"| node_admins
node_admins -->|"analyzes policies"| node_iamaudit
node_cli -->|"dispatches to"| node_report
node_report -->|"includes findings"| node_auditengine
node_report -->|"includes exposure data"| node_public
node_report -->|"uses resource model"| node_nodes
node_cli -->|"dispatches to"| node_iamreport
node_iamreport -->|"uses resource model"| node_nodes
node_cli -->|"dispatches to"| node_prepare
node_prepare -->|"builds resource model"| node_nodes
node_prepare -->|"reads account data"| node_dataset
node_operator -->|"starts server"| node_webserver
node_webserver -.->|"serves map"| node_webmap
node_cli -->|"dispatches to"| node_public
node_cli -->|"dispatches to"| node_unused
node_cli -->|"dispatches to"| node_stats
node_cli -->|"dispatches to"| node_sgips
node_cli -->|"dispatches to"| node_trust
node_cli -.->|"dispatches to"| node_organization
node_auditorstack -->|"configures forwarder"| node_auditorlambda

click node_cli "https://github.com/duo-labs/cloudmapper/blob/main/cloudmapper.py"
click node_collect "https://github.com/duo-labs/cloudmapper/blob/main/commands/collect.py"
click node_dataset "https://github.com/duo-labs/cloudmapper/tree/main/account-data"
click node_auditcmd "https://github.com/duo-labs/cloudmapper/blob/main/commands/audit.py"
click node_auditengine "https://github.com/duo-labs/cloudmapper/blob/main/shared/audit.py"
click node_iamaudit "https://github.com/duo-labs/cloudmapper/blob/main/shared/iam_audit.py"
click node_admins "https://github.com/duo-labs/cloudmapper/blob/main/commands/find_admins.py"
click node_report "https://github.com/duo-labs/cloudmapper/blob/main/commands/report.py"
click node_iamreport "https://github.com/duo-labs/cloudmapper/blob/main/commands/iam_report.py"
click node_prepare "https://github.com/duo-labs/cloudmapper/blob/main/commands/prepare.py"
click node_webserver "https://github.com/duo-labs/cloudmapper/blob/main/commands/webserver.py"
click node_webmap "https://github.com/duo-labs/cloudmapper/blob/main/web/js/cloudmap.js"
click node_public "https://github.com/duo-labs/cloudmapper/blob/main/commands/public.py"
click node_unused "https://github.com/duo-labs/cloudmapper/blob/main/commands/find_unused.py"
click node_stats "https://github.com/duo-labs/cloudmapper/blob/main/commands/stats.py"
click node_sgips "https://github.com/duo-labs/cloudmapper/blob/main/commands/sg_ips.py"
click node_trust "https://github.com/duo-labs/cloudmapper/blob/main/commands/weboftrust.py"
click node_organization "https://github.com/duo-labs/cloudmapper/blob/main/shared/organization.py"
click node_query "https://github.com/duo-labs/cloudmapper/blob/main/shared/query.py"
click node_nodes "https://github.com/duo-labs/cloudmapper/blob/main/shared/nodes.py"
click node_common "https://github.com/duo-labs/cloudmapper/blob/main/shared/common.py"
click node_auditorstack "https://github.com/duo-labs/cloudmapper/blob/main/auditor/lib/cloudmapperauditor-stack.js"
click node_auditorlambda "https://github.com/duo-labs/cloudmapper/blob/main/auditor/resources/alarm_forwarder/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_collect,node_dataset,node_query toneBlue
class node_auditcmd,node_auditengine,node_iamaudit,node_admins,node_public,node_unused,node_common toneAmber
class node_report,node_iamreport,node_prepare,node_webserver,node_webmap,node_nodes toneMint
class node_stats,node_sgips,node_trust,node_organization toneRose
class node_auditorstack,node_auditorlambda,node_operator,node_aws toneIndigo
```

## Components

### CLI and collection

- [Command dispatcher](https://github.com/duo-labs/cloudmapper/blob/main/cloudmapper.py): `cloudmapper.py`
- [AWS metadata collection](https://github.com/duo-labs/cloudmapper/blob/main/commands/collect.py): `commands/collect.py`
- [Account JSON data](https://github.com/duo-labs/cloudmapper/tree/main/account-data): `account-data`
- [Collected-data reader](https://github.com/duo-labs/cloudmapper/blob/main/shared/query.py): `shared/query.py`

### Security analysis

- [Misconfiguration audit](https://github.com/duo-labs/cloudmapper/blob/main/commands/audit.py): `commands/audit.py`
- [Audit rules](https://github.com/duo-labs/cloudmapper/blob/main/shared/audit.py): `shared/audit.py`
- [IAM policy analysis](https://github.com/duo-labs/cloudmapper/blob/main/shared/iam_audit.py): `shared/iam_audit.py`
- [Admin discovery](https://github.com/duo-labs/cloudmapper/blob/main/commands/find_admins.py): `commands/find_admins.py`
- [Public exposure scan](https://github.com/duo-labs/cloudmapper/blob/main/commands/public.py): `commands/public.py`
- [Unused resource scan](https://github.com/duo-labs/cloudmapper/blob/main/commands/find_unused.py): `commands/find_unused.py`
- [Shared analysis utilities](https://github.com/duo-labs/cloudmapper/blob/main/shared/common.py): `shared/common.py`

### Reports and mapping

- [Account report](https://github.com/duo-labs/cloudmapper/blob/main/commands/report.py): `commands/report.py`
- [IAM report](https://github.com/duo-labs/cloudmapper/blob/main/commands/iam_report.py): `commands/iam_report.py`
- [Network preparation](https://github.com/duo-labs/cloudmapper/blob/main/commands/prepare.py): `commands/prepare.py`
- [Local web server](https://github.com/duo-labs/cloudmapper/blob/main/commands/webserver.py): `commands/webserver.py`
- [Network map UI](https://github.com/duo-labs/cloudmapper/blob/main/web/js/cloudmap.js): `web/js/cloudmap.js`
- [AWS resource model](https://github.com/duo-labs/cloudmapper/blob/main/shared/nodes.py): `shared/nodes.py`

### Account insights

- [Resource statistics](https://github.com/duo-labs/cloudmapper/blob/main/commands/stats.py): `commands/stats.py`
- [Security-group IPs](https://github.com/duo-labs/cloudmapper/blob/main/commands/sg_ips.py): `commands/sg_ips.py`
- [Web of trust](https://github.com/duo-labs/cloudmapper/blob/main/commands/weboftrust.py): `commands/weboftrust.py`
- [Organization discovery](https://github.com/duo-labs/cloudmapper/blob/main/shared/organization.py): `shared/organization.py`

### CloudMapper Auditor

- [Auditor infrastructure](https://github.com/duo-labs/cloudmapper/blob/main/auditor/lib/cloudmapperauditor-stack.js): `auditor/lib/cloudmapperauditor-stack.js`
- [Alarm forwarder](https://github.com/duo-labs/cloudmapper/blob/main/auditor/resources/alarm_forwarder/main.py): `auditor/resources/alarm_forwarder/main.py`

### Other components

- **Operator**
- **AWS account**

## Connections

- Operator → Command dispatcher: runs commands
- Command dispatcher → AWS metadata collection: dispatches to (evidence: `cloudmapper.py`)
- Operator → AWS metadata collection: requests collection
- AWS metadata collection → AWS account: reads metadata
- AWS metadata collection → Account JSON data: records JSON
- Account JSON data → Collected-data reader: loads data (evidence: `shared/query.py`)
- Command dispatcher → Misconfiguration audit: dispatches to (evidence: `cloudmapper.py`)
- Misconfiguration audit → Audit rules: runs checks (evidence: `commands/audit.py`)
- Audit rules → Collected-data reader: reads collected data (evidence: `shared/audit.py`)
- Audit rules → IAM policy analysis: uses IAM checks (evidence: `shared/audit.py`)
- Command dispatcher → Admin discovery: dispatches to (evidence: `cloudmapper.py`)
- Admin discovery → IAM policy analysis: analyzes policies (evidence: `commands/find_admins.py`)
- Command dispatcher → Account report: dispatches to (evidence: `cloudmapper.py`)
- Account report → Audit rules: includes findings (evidence: `commands/report.py`)
- Account report → Public exposure scan: includes exposure data (evidence: `commands/report.py`)
- Account report → AWS resource model: uses resource model (evidence: `commands/report.py`)
- Command dispatcher → IAM report: dispatches to (evidence: `cloudmapper.py`)
- IAM report → AWS resource model: uses resource model (evidence: `commands/iam_report.py`)
- Command dispatcher → Network preparation: dispatches to (evidence: `cloudmapper.py`)
- Network preparation → AWS resource model: builds resource model (evidence: `commands/prepare.py`)
- Network preparation → Account JSON data: reads account data (evidence: `commands/prepare.py`)
- Operator → Local web server: starts server
- Local web server → Network map UI: serves map
- Command dispatcher → Public exposure scan: dispatches to (evidence: `cloudmapper.py`)
- Command dispatcher → Unused resource scan: dispatches to (evidence: `cloudmapper.py`)
- Command dispatcher → Resource statistics: dispatches to (evidence: `cloudmapper.py`)
- Command dispatcher → Security-group IPs: dispatches to (evidence: `cloudmapper.py`)
- Command dispatcher → Web of trust: dispatches to (evidence: `cloudmapper.py`)
- Command dispatcher → Organization discovery: dispatches to
- Auditor infrastructure → Alarm forwarder: configures forwarder (evidence: `auditor/lib/cloudmapperauditor-stack.js`)
