AWS CLI 实战：使用 `accessanalyzer list-findings-v2` 检索并过滤 IAM Access Analyzer 发现结果-平芜编程栈

AWS CLI 实战：使用`accessanalyzer list-findings-v2`检索并过滤 IAM Access Analyzer 发现结果

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

IAM Access Analyzer 会在分析资源策略后生成"发现结果（finding）"，标识账户信任边界之外的外部访问、未使用访问或内部访问风险。本指南基于 AWS CLI 官方示例文档，完整讲解aws accessanalyzer list-findings-v2命令的用法：如何指定 analyzer、如何用--filter按资源与资源类型精确筛选、如何理解返回结果的结构，并结合本仓库的 AWS CLI 服务模型源码（service-2.json）剖析每个参数的底层定义、支持的操作符与分页机制，让你能直接复制命令投入安全审计实战。

命令概述：`list-findings-v2`能做什么

list-findings-v2用于检索指定 analyzer（分析器）生成的发现结果列表。从 AWS CLI 的 botocore 服务模型可以看到该操作的完整定义（见 service-2.json）：

HTTP 方法为POST，请求 URI 为/findingv2，成功响应码为200；
该操作是只读操作（"readonly": true）；
可能抛出的异常包括ResourceNotFoundException、ValidationException、InternalServerException、ThrottlingException和AccessDeniedException。

模型文档中还明确指出一个关键事实：ListFindings与ListFindingsV2在 IAM 策略中都对应access-analyzer:ListFindings这一 Action，即执行本命令前，调用者必须拥有access-analyzer:ListFindings权限；同时，旧版ListFindings仅支持外部访问（external access）分析器，而内部访问（internal access）和未使用访问（unused access）分析器必须使用ListFindingsV2——这也是日常运维中优先使用 V2 版本的重要原因。

基本用法：检索指定 analyzer 的发现结果

原文档给出的第一个典型场景是：检索账户中指定 analyzer 生成的发现结果，并通过过滤条件只保留名称包含Cognito的 IAM 角色。命令如下：

aws accessanalyzer list-findings-v2 \ --analyzer-arn arn:aws:access-analyzer:us-west-2:111122223333:analyzer/ConsoleAnalyzer-account \ --filter '{"resource": {"contains": ["Cognito"]}, "resourceType": {"eq": ["AWS::IAM::Role"]}}'

参数拆解

--analyzer-arn（必填）：要从中检索发现结果的分析器 ARN。在请求模型ListFindingsV2Request中它是唯一的必填字段（见 service-2.json）。示例中的arn:aws:access-analyzer:us-west-2:111122223333:analyzer/ConsoleAnalyzer-account表明这是一个在us-west-2区域、由账户111122223333创建、名为ConsoleAnalyzer-account的分析器。实际使用时请替换为aws accessanalyzer list-analyzers输出的真实 ARN。
--filter（可选）：一个 JSON 格式的过滤条件，键为 IAM Access Analyzer 的过滤键（filter key，如resource、resourceType、principal、action等），值为对应的匹配准则（Criterion）。上面的示例同时叠加了两个条件：
- "resource": {"contains": ["Cognito"]}：资源的 ARN 中包含子串Cognito；
- "resourceType": {"eq": ["AWS::IAM::Role"]}：资源类型严格等于AWS::IAM::Role。

实际输出示例

执行上述命令后，返回的 JSON 输出如下（来自原文档）：

{ "findings": [ { "analyzedAt": "2024-02-16T18:17:47.888000+00:00", "createdAt": "2021-02-26T21:17:24.710000+00:00", "id": "597f3bc2-3adc-4c18-9879-5c4b23485e46", "resource": "arn:aws:iam::111122223333:role/Cognito_testpoolUnauth_Role", "resourceType": "AWS::IAM::Role", "resourceOwnerAccount": "111122223333", "status": "ACTIVE", "updatedAt": "2021-02-26T21:17:24.710000+00:00", "findingType": "ExternalAccess" }, { "analyzedAt": "2024-02-16T18:17:47.888000+00:00", "createdAt": "2021-02-26T21:17:50.905000+00:00", "id": "ce0e221a-85b9-4d52-91ff-d7678075442f", "resource": "arn:aws:iam::111122223333:role/Cognito_testpoolAuth_Role", "resourceType": "AWS::IAM::Role", "resourceOwnerAccount": "111122223333", "status": "ACTIVE", "updatedAt": "2021-02-26T21:17:50.905000+00:00", "findingType": "ExternalAccess" } ] }

可见过滤条件生效：返回的两条结果都是名称包含Cognito的 IAM 角色（Cognito_testpoolUnauth_Role与Cognito_testpoolAuth_Role），分别对应未认证（Unauth）与已认证（Auth）两种身份池角色。

深入理解过滤条件：Criterion 的四种操作符

--filter参数的底层类型是FilterCriteriaMap——一个"键为字符串、值为Criterion结构体"的 Map（见 service-2.json）。每个Criterion支持四种操作符，且可组合使用（见 service-2.json）：

操作符	含义	取值类型
`eq`	等于	字符串列表，命中任意一个即匹配
`neq`	不等于	字符串列表，排除其中任意值
`contains`	包含子串	字符串列表，命中任意一个子串即匹配
`exists`	是否存在	布尔值（`true`/`false`）

对应到 CLI 的 JSON 写法：

# 等于：查找状态为 ACTIVE 的发现结果 --filter '{"status": {"eq": ["ACTIVE"]}}' # 不等于：排除所有 S3 桶相关结果 --filter '{"resourceType": {"neq": ["AWS::S3::Bucket"]}}' # 包含：查找资源 ARN 中包含 prod 的结果 --filter '{"resource": {"contains": ["prod"]}}' # 存在：查找带有特定错误信息的结果 --filter '{"error": {"exists": true}}' # 多条件叠加：同时满足多个键 --filter '{"status": {"eq": ["ACTIVE"]}, "resourceType": {"contains": ["AWS::S3"]}}'

提示：关于可用过滤键的完整清单，可查阅 AWS 官方 IAM User Guide 中的 "IAM Access Analyzer filter keys"（原文档中给出的参考链接）。本仓库仅封装 AWS API，过滤键本身由 IAM Access Analyzer 服务定义。

更多参数：排序与分页

ListFindingsV2Request除analyzerArn与filter外，还支持maxResults、nextToken和sort三个参数（见 service-2.json）。

使用`--sort`控制排序

sort参数对应SortCriteria结构体（见 service-2.json），包含两个字段：

attributeName：参与排序的字段名（如createdAt、updatedAt、resourceType等）；
orderBy：排序方向，取值为ASC（升序）或DESC（降序）。

# 按创建时间降序，最新的发现结果排在最前 aws accessanalyzer list-findings-v2 \ --analyzer-arn arn:aws:access-analyzer:us-west-2:111122223333:analyzer/ConsoleAnalyzer-account \ --sort '{"attributeName": "createdAt", "orderBy": "DESC"}'

使用`--max-results`与`--next-token`分页

当结果集较大时，单次响应最多返回由maxResults指定的条数（Integer类型），并通过响应中的nextToken提供下一页游标（见 service-2.json）。对应的分页配置也完整定义在 paginators-1.json 中：input_token与output_token均为nextToken，limit_key为maxResults，result_key为findings。

这意味着除了手动拼接游标，你还可以直接利用 AWS CLI 内置的分页能力——追加--page-size（对应每次 API 请求的 maxResults）并使用--no-paginate之外的默认分页行为，或通过--starting-token从指定位置继续：

# 每页 20 条，自动翻页并聚合所有结果 aws accessanalyzer list-findings-v2 \ --analyzer-arn arn:aws:access-analyzer:us-west-2:111122223333:analyzer/ConsoleAnalyzer-account \ --page-size 20 # 手动分页：拿到第一页后，用 nextToken 取下一页 aws accessanalyzer list-findings-v2 \ --analyzer-arn arn:aws:access-analyzer:us-west-2:111122223333:analyzer/ConsoleAnalyzer-account \ --max-results 20 \ --next-token <上一步返回的nextToken>

响应结构详解：`FindingSummaryV2`的字段含义

响应中的findings列表元素类型为FindingSummaryV2（见 service-2.json），必填字段包括analyzedAt、createdAt、id、resourceType、resourceOwnerAccount、status与updatedAt。各字段说明如下：

字段	说明
`analyzedAt`	生成该发现结果的资源策略或 IAM 实体被分析的时刻
`createdAt`	发现结果被创建的时刻
`updatedAt`	发现结果最近一次被更新的时刻
`id`	发现结果的唯一 ID（后续可用`get-finding-v2 --id <id>`获取详情）
`resource`	被外部主体访问的具体资源 ARN（如`arn:aws:iam::111122223333:role/Cognito_testpoolUnauth_Role`）
`resourceType`	资源类型（如`AWS::IAM::Role`、`AWS::S3::Bucket`）
`resourceOwnerAccount`	拥有该资源的 AWS 账户 ID
`status`	发现结果状态，如`ACTIVE`（活跃）、`ARCHIVED`（已归档）、`RESOLVED`（已解决）
`error`	当发现结果类型为 Error 时携带的错误信息
`findingType`	发现结果的类型（见下文）

`findingType`的取值与适用场景

FindingType的枚举定义见 service-2.json：

ExternalAccess：外部访问发现结果，来自外部访问分析器，标识信任区之外的实体对资源有访问权限（示例输出中的两条记录即为此类型）；
UnusedIAMRole、UnusedIAMUserAccessKey、UnusedIAMUserPassword、UnusedPermission：未使用访问发现结果，来自未使用访问分析器；
InternalAccess：内部访问发现结果，来自内部访问分析器。

由于ListFindingsV2同时支持以上全部三种分析器类型（而旧版ListFindings仅支持外部访问分析器），因此findingType字段是你区分结果来源、按类型进一步审计的关键维度。

前置条件与权限要求

调用list-findings-v2前需满足：

已创建 Access Analyzer：需要通过控制台或aws accessanalyzer create-analyzer创建分析器，并拿到其 ARN；
IAM 权限：调用者必须具有access-analyzer:ListFindings权限（ListFindings与ListFindingsV2共用该 Action）。一个最小化的策略示例：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "access-analyzer:ListFindings", "Resource": "arn:aws:access-analyzer:*:*:analyzer/*" } ] }

区域一致性：--analyzer-arn中的区域必须与 CLI 当前配置的区域一致，否则会命中ResourceNotFoundException或AccessDeniedException。

与旧版`list-findings`的选择建议

服务模型文档（见 service-2.json）明确提示：ListFindings仅支持外部访问分析器，内部访问与未使用访问分析器必须使用ListFindingsV2。此外，V2 版本在FindingSummaryV2中新增了findingType字段，能更清晰地标识结果类型。因此在新项目中应统一优先使用list-findings-v2；只有当你确认只涉及外部访问分析器且依赖旧版响应结构时，才考虑使用list-findings。

AWS CLI 实战：使用 `accessanalyzer list-findings-v2` 检索并过滤 IAM Access Analyzer 发现结果