CloudMapper 网络可视化实战指南:用 `prepare` 与 `webserver` 绘制 AWS VPC 拓扑图

原创2026-10-14 23:00:022,276 阅读
文章标签:网络安全应用安全云原生

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),流程如下:

  1. 建立 security group → 挂载该组的实例 的映射(sg_to_instance_mapping)。
  2. 遍历每个安全组的 IpPermissions:
    • CIDR 入站:对私网 CIDR,若 --internal-edges 开启,则在当前 VPC 及所有对等 VPC(peers)中查找 IP 落在该 CIDR 内的实例,让它们与目标组内所有实例连线;对外部 CIDR,仅当目标实例 is_public 时才从外部 CIDR 节点连向实例,并把 0.0.0.0/0 且非公网的资源标记为 VPC 内全可达。
    • 安全组引用入站(UserIdGroupPairs):源组实例 → 目标组实例。
  3. 对拥有无限制入站(has_unrestricted_ingress,典型如 VPC Endpoint)的目标,VPC 内及对等 VPC 的所有资源都连向它。
  4. 删除"不能发起流量"的源节点(如 RDS、VPC Endpoint、Redshift、ElasticSearch 等类型的 can_egress 为 False,见 shared/nodes.py、shared/nodes.py、shared/nodes.py、shared/nodes.py),并跳过源等于目标的环边。
  5. 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 仍被测试覆盖、可正常使用。
登录后查看全文
cloudmapper