CloudMapper 网络可视化实战指南:用 `prepare` 与 `webserver` 绘制 AWS VPC 拓扑图
CloudMapper 网络可视化实战指南:用 prepare 与 webserver 绘制 AWS VPC 拓扑图
CloudMapper 的 prepare 与 webserver 两条命令构成了完整的"数据采集 → 拓扑生成 → 浏览器交互式查看"链路:前者把已采集的 AWS 元数据转换为 Cytoscape.js 可渲染的 web/data.json,后者在本地启动一个只读 Web 服务器把画布呈现给你。读完本文,你将掌握全部过滤参数(按区域、VPC、标签裁剪拓扑)、理解"边只来源于安全组入站规则"的底层构图原理,并熟练使用删除、高亮、折叠、随机布局、导出导入等全部交互操作,用于审计网络暴露面或汇报架构。
前置条件:本文假设你已经完成了账户配置(config.json)与元数据采集(collect 命令),且工作目录下存在 account-data/<account>/... 格式的采集产物。仓库自带的演示数据位于 account-data/demo,可直接用于上手体验。
一、可视化范围:只看 VPC 内的"安全组挂载者"
网络可视化不会展示账户里的全部资源,它有明确的边界:
- 只显示 VPC 内资源,即所有挂了 Security Group 的对象,包括:EC2、RDS、ELB(经典版与 v2)、Redshift、ElasticSearch、ECS、Lambda,以及 VPC Endpoints(S3/DynamoDB 的 Gateway Endpoint 与 PrivateLink)。
- 不显示 S3 桶。只有在账户里显式创建了指向 S3 服务的 Gateway Endpoint 时,图中才会出现这条 S3 服务边——你的 AWS 账户默认没有该端点。
- Lambda 等资源只有位于 VPC 内部时才会展示。这一点在源码中同样有体现:commands/prepare.py 的
get_lambda_functions只保留VpcConfig != null的函数。 - 边的生成只看安全组的入站(ingress)规则,不考虑资源策略(resource policy)、Network ACL 与路由表(Route Table)。源码注释明确写道:"Only looking at Security Groups currently, which are a VPC level construct"(commands/prepare.py)。因此该图反映的是"安全组层面谁能访问谁",而非网络层面最终可达性。
此外,同一 VPC 中所有 0.0.0.0/0 入站且没有公网 IP 的资源,会被标记为"允许 VPC 内所有资源访问";而外部 CIDR(如 1.1.1.1/32)只有目标资源具有公网 IP 时才会建立连接(详见 commands/prepare.py 的 get_connections 逻辑)。
二、Prepare 数据:把采集结果变成可渲染的 JSON
执行以下命令即可把已采集的账户数据转换为浏览器可用的图数据:
python cloudmapper.py prepare --account my_account
命令默认读取 config.json(可通过 --config 指定其他文件名),并把结果写入 web/data.json。prepare 的入口是 commands/prepare.py:build_data_structure 遍历账户 → 区域 → VPC → AZ → 子网,为每个存活节点生成 Cytoscape JSON(含 id、name、type、local_id、node_data 等字段,见 shared/nodes.py 的 cytoscape_data),最后写入文件。若传入 --no-node-data,则节点中的 node_data 会被清空以减小文件体积。
值得注意的是,prepare 在源码中被标记为 "NO LONGER MAINTAINED"(commands/prepare.py),运行时会打印维护警告,但其核心构图函数 build_data_structure 仍然稳定,并被 tests/unit/test_prepare.py 的测试直接覆盖。
2.1 全部命令行参数速查表
以下参数与 commands/prepare.py 中 argparse 的定义一一对应,括号内为该参数在源码中的默认值:
| 参数 | 作用 | 默认值 |
|---|---|---|
--config |
指定配置文件(如 config.json) |
config.json |
--account |
指定要构图的账户名 | 无(必填) |
--regions |
只显示指定区域,逗号分隔,如 us-east-1,us-east-2 |
全部区域 |
--vpc-ids |
只显示指定 VPC,如 vpc-1234,vpc-abcd |
全部 VPC |
--vpc-names |
只显示指定名称的 VPC,如 prod,dev |
全部 VPC |
--tags |
按标签过滤节点,可重复使用以 OR 多个标签集 | 不过滤 |
--internal-edges |
显示 VPC 内部边 | 开(True) |
--no-internal-edges |
只显示指向外部 CIDR 的边 | — |
--inter-rds-edges |
显示 RDS 节点之间的边 | 关(False) |
--no-inter-rds-edges |
不显示 RDS 之间的边 | — |
--read-replicas |
显示 RDS 只读副本节点 | 开(True) |
--no-read-replicas |
忽略 RDS 只读副本 | — |
--azs |
显示可用区(Availability Zone)节点 | 开(True) |
--no-azs |
不显示可用区,子网直接挂到 VPC 下 | — |
--collapse-by-tag |
把拥有同一标签值的节点折叠为一个显示节点 | 无 |
--collapse-asgs |
自动缩放组折叠为单个节点 | 开(True) |
--no-collapse-asgs |
展开显示自动缩放组内的所有实例 | — |
--no-node-data |
生成的 JSON 中不携带节点原始数据 | 携带(True) |
三、过滤选项详解:从源码看真实行为
大环境(数百节点、上千条边)往往无法顺畅渲染,过滤是让图"既好看又跑得动"的关键。下面结合源码逐项解读。
3.1 按区域与 VPC 裁剪:--regions / --vpc-ids / --vpc-names
这三个参数在 commands/prepare.py 的 get_vpcs 中被编译成 jq 过滤器:vpc-ids 用 contains 匹配 VPC ID,vpc-names 则要求 VPC 的 Name 标签值包含给定字符串(--vpc-names Prod 会命中名为 Prod 的 VPC,演示数据中的 VPC 正是如此,参见 tests/unit/test_prepare.py)。区域过滤则作用于 get_regions 层面,只保留你列出的区域。
3.2 标签过滤:--tags 的 AND/OR 语义
--tags 的参数语义值得精确理解:单个标签集内部用逗号分隔的键值对做 AND,多个 --tags 之间做 OR。例如:
--tags Env=Prod --tags Env=Test,Name=Bastion
等价于:(Env=Prod) OR (Env=Test AND Name=Bastion)。实现位于 commands/prepare.py:对每个节点,先按逗号切分条件、再逐条匹配节点 Tags,只有某组条件全部命中才算该标签集匹配;所有标签集都未匹配的节点会被移除。标签键值对通过 tag.get("Key") == key and tag.get("Value") == value 精确匹配。
3.3 折叠策略:--collapse-by-tag 与 --no-collapse-asgs
--collapse-by-tag Env:所有Env标签值相同的 EC2 会被折叠成一个"分组 EC2"节点,节点类型变为grouped_ec2,local_id 为grouped_ec2_<标签值>(见 shared/nodes.py)。对于有成组成百上千实例的环境,这是最有效的降噪手段。--collapse-asgs(默认开):若实例带有aws:autoscaling:groupName标签,则该自动缩放组折叠为单个类型为autoscaling的节点;--no-collapse-asgs则把组内每个实例都画出来(shared/nodes.py)。
3.4 边的取舍:--internal-edges / --inter-rds-edges / --read-replicas
--no-internal-edges:跳过所有私网 CIDR 的入站规则,只保留外部 CIDR → 资源(以及0.0.0.0/0相关)的边。当你想回答"哪些资源对公网暴露"时最有用。测试表明同一演示数据下,关掉内部边后边数从 35 条降到 19 条(tests/unit/test_prepare.py)。--inter-rds-edges:RDS 之间的通信路径默认不画(--no-inter-rds-edges为默认),因为通常不关心;需要展示时显式开启。源码中通过判断源/目标节点的node_type是否为rds/rds_rr来跳过(commands/prepare.py)。--no-read-replicas:默认展示 RDS 只读副本(rds_rr类型节点);关闭后这些副本在get_resource_nodes阶段就被跳过(commands/prepare.py)。
3.5 AZ 层级:--azs / --no-azs
默认显示可用区节点,子网挂在 AZ 下;--no-azs 时子网直接以 VPC 为父节点(commands/prepare.py)。如果你只关心 VPC 与子网两层结构,用 --no-azs 让图更清爽。
四、底层构图原理:安全组入站规则如何变成边
了解构图原理有助于正确解读图,也可用于排查"为什么这条边没有出现"。核心在 get_connections(commands/prepare.py),流程如下:
- 建立
security group → 挂载该组的实例的映射(sg_to_instance_mapping)。 - 遍历每个安全组的
IpPermissions:- CIDR 入站:对私网 CIDR,若
--internal-edges开启,则在当前 VPC 及所有对等 VPC(peers)中查找 IP 落在该 CIDR 内的实例,让它们与目标组内所有实例连线;对外部 CIDR,仅当目标实例is_public时才从外部 CIDR 节点连向实例,并把0.0.0.0/0且非公网的资源标记为 VPC 内全可达。 - 安全组引用入站(
UserIdGroupPairs):源组实例 → 目标组实例。
- CIDR 入站:对私网 CIDR,若
- 对拥有无限制入站(
has_unrestricted_ingress,典型如 VPC Endpoint)的目标,VPC 内及对等 VPC 的所有资源都连向它。 - 删除"不能发起流量"的源节点(如 RDS、VPC Endpoint、Redshift、ElasticSearch 等类型的
can_egress为False,见 shared/nodes.py、shared/nodes.py、shared/nodes.py、shared/nodes.py),并跳过源等于目标的环边。 - VPC Peering 通过
ec2-describe-vpc-peering-connections建立addPeer关系(commands/prepare.py),因此对等 VPC 之间的实例也会被纳入内部边计算。
4.1 外部 CIDR 的命名与归并
所有外部网段会生成 ip 类型的节点。图中显示的名称由 config.json 的 cidrs 字段决定,例如 config.json.demo:
{
"cidrs": {
"1.1.1.1/32": {"name": "SF Office"},
"2.2.2.2/28": {"name": "NY Office"}
}
}
构图时会把出现在安全组里的外部 CIDR 与配置中的命名网段做"最小匹配归并":如果一个外部 CIDR 落在某个已命名 CIDR 范围内,就归并到其中最小的那个命名网段,并以其 name 作为节点显示名(commands/prepare.py)。未被配置命名的网段则直接以 CIDR 字符串展示。只有被实际用到的外部 CIDR(is_used)才会被写入 JSON。
4.2 大图预警
build_data_structure 内置了体量警示:当节点数超过 200 或边数超过 500 时,会在终端打印 WARNING,提示该图"难以展示、可能复杂到无法理解",并建议用单区域、忽略内部边等过滤手段减负(commands/prepare.py)。
五、启动 Web 服务器
构图完成后,用任意 Web 服务器托管 web 目录即可查看,或者直接用内置服务器:
python cloudmapper.py webserver
默认监听 127.0.0.1:8000。可选参数(见 commands/webserver.py):
| 参数 | 作用 |
|---|---|
--port <N> |
指定监听端口(默认 8000) |
--public |
允许来自 0.0.0.0(或启用 IPv6 时的 ::)的连接,而非仅本机 localhost |
--ipv6 |
改用 IPv6 监听(::1),配合 --public 时为 :: |
服务器基于 SimpleHTTPRequestHandler 定制,为所有响应附加了 Cache-Control: no-cache, no-store, must-revalidate 等禁缓存头(保证修改 web/data.json 后刷新即可看到新图),并注册了 .svg 的 image/svg+xml MIME 类型以正确渲染图标。安全提示:除非确有必要,不要在生产/共享环境中使用 --public,因为它会把包含网络拓扑的页面暴露给网络上的任意客户端。
六、浏览器交互指南:鼠标、键盘与命令按钮
打开 http://127.0.0.1:8000(或你自行托管的地址)即可开始操作。工具栏按钮与键盘快捷键的对应关系可从 web/index.html 与 web/js/cloudmap.js 交叉确认。
6.1 鼠标操作
- 平移与缩放:使用界面右下角控件,或用方向键平移、
+/-键缩放。 - 选中节点:单击节点,背景变黄;在空白处单击或按住 Shift 再单击已选节点可取消选中。
- 多选:按住 Shift 单击多个节点;或按住 Shift 拖拽框选区域,所有与选框相交的节点都会被选中。
- 移动节点:单击节点并拖动即可调整布局。
6.2 命令按钮(含键盘快捷键)
| 操作 | 按钮(图标) | 快捷键 | 行为 |
|---|---|---|---|
| 删除/隐藏节点 | 带斜线的眼睛 | d |
选中节点后点击,节点被隐藏;点击眼睛图标可恢复(undelete)所有被删除节点。被删除节点的所有邻居会获得黑色边框;双击带黑色边框的节点可恢复其被删除的邻居 |
| 高亮邻居 | 相连节点符号(share-alt) | h |
只高亮选中节点的邻居,便于看清连接关系;点击反向符号(share-alt-square)取消高亮 |
| 折叠全部 / 展开全部 | 相向箭头 / 背向箭头 | — | 折叠所有可折叠节点,或恢复全部已折叠节点 |
| 折叠 / 展开选中 | 减号 / 加号 | c / e |
折叠或展开选中节点(支持递归展开/折叠) |
| 随机布局 | 锤子 | r |
以随机方式重新排布整张图 |
| 保存图片 | 相机 | — | 导出高分辨率图片。当节点很多、必须缩小到看不清细节时,比截图更实用(调用 saveImage,见 web/js/cloudmap.js) |
| 导出 / 导入布局 | 下载 / 上传 | — | 把当前布局保存为 JSON 文件,之后可重新上传恢复。适合手动调整节点位置后"存档";注意重新打开存档文件仍存在一些已知 bug |
工具栏按钮图标如下:
CloudMapper 工具栏命令图标
删除与高亮的实际效果可参考文档中的示意:删除节点后其邻居带黑色边框(deleted_node.png),高亮邻居后仅保留焦点节点的连接(highlight_neighbors.png),折叠节点后相关子树收拢为单一节点(collapsed_node.png)。
七、初始布局:为什么每次打开都要手动整理
首次打开时布局几乎从不理想。CloudMapper 选用的是当前公认最适合复合节点图(compound node diagram)的布局算法 CoSE(cytoscape.js-cose-bilkent,即 web/js/cytoscape-cose-bilkent.js),但即便如此,仍需要你通过拖拽节点做人工微调。下图是打开演示账户时最可能看到的初始样子:
CloudMapper 演示环境初始布局
调整到位后,建议用"导出布局"保存 JSON 存档,配合"保存图片"输出高分辨率成果,两者结合可形成"整理一次、多次复用"的工作流。
八、验证与测试:如何确认构图逻辑正确
仓库为 prepare 构图逻辑提供了可重复的单元测试(tests/unit/test_prepare.py),它直接使用 account-data/demo 的演示数据断言输出结构:
- 外部 CIDR 判定:
1.1.1.1/32为外部、10.0.0.0/32为内部(对应 shared/common.py 中is_external_cidr对 RFC1918 网段的判定)。 - 完整构图(
build_data_structure):默认输出 35 条边、2 个ip节点、2 个rds、3 个ec2、2 个elb、1 个elbv2、4 个子网、1 个区域、1 个 VPC,以及 redshift/elasticsearch/lambda/ecs/sqs/s3 各若干(tests/unit/test_prepare.py)。 - 过滤行为:
internal_edges=False时边数降为 19;azs=True时出现 2 个az节点;--vpc-names Prod时仅保留 3 个ec2节点(tests/unit/test_prepare.py)。
这些断言与实际行为一致,可作为你调试自定义过滤参数的参考基线。
九、常见问题与限制小结
- 图里没有 S3 桶? 正常——除非你创建了指向 S3 的 Gateway Endpoint。
- 看不到某个 Lambda/ECS? 它们必须部署在 VPC 内才会被收录。
- 边与预期不符? 边只来自安全组入站规则,不含 NACL、路由表与资源策略;
0.0.0.0/0且无公网 IP 的资源会表现为"VPC 内全可达"。 - 图太大打不开? 优先用
--no-internal-edges、--regions、--collapse-by-tag减负;节点 > 200 或边 > 500 时命令行会给出显式警告。 prepare打印维护警告? 该命令被标记为不再维护,但构图核心build_data_structure仍被测试覆盖、可正常使用。