Cloud Custodian Azure 入门到实战:用 `azure.entraid-user` 策略按部门筛选 Entra ID 用户
Cloud Custodian Azure 入门到实战:用 azure.entraid-user 策略按部门筛选 Entra ID 用户
Cloud Custodian(c7n)是一个以 YAML 描述策略的云安全、成本优化与治理规则引擎,本文聚焦其 Azure 提供方(c7n_azure)中的 Entra ID 用户资源 azure.entraid-user。你将学会如何编写一条按 department 字段筛选 IT 部门用户的策略,理解 value 过滤器在底层如何工作,并掌握从运行策略到查看结果的完整闭环,为后续扩展到禁用账号、MFA 审计等安全治理场景打下基础。
策略骨架:资源、过滤器与动作
Cloud Custodian 的策略本质上是一个三要素结构:resource(要作用的资源类型)、filters(缩小资源集合的条件)、actions(对筛选结果执行的动作)。Azure 入门文档 对这一结构给出了精确定义,而本文示例的 IT 部门用户筛选策略只用到前两要素:
policies:
- name: it-department-users
resource: azure.entraid-user
description: |
Find users in the IT department.
This policy demonstrates filtering by department field.
Modify the department value to match your organization's structure.
filters:
- type: value
key: accountEnabled
value: true
- type: value
key: department
value: IT
策略的核心语义非常直白:列出租户内所有 Entra ID 用户,先保留 accountEnabled 为 true 的启用账号,再从中筛选 department 字段值等于 IT 的用户。文档注释特意提醒:department 的取值需要按你所在组织的实际部门结构修改,这是一个可复用的模板而非写死的配置。
azure.entraid-user 资源:基于 Microsoft Graph API 的用户管理器
azure.entraid-user 在源码中对应 tools/c7n_azure/c7n_azure/resources/entraid_user.py 中的 EntraIDUser 类。与多数通过 Azure Resource Manager API 查询的 Azure 资源不同,它继承自 GraphResourceManager(定义于 tools/c7n_azure/c7n_azure/graph_utils.py),数据源是 Microsoft Graph API 的 users 端点。
关键实现事实(来自源码,可自行核对):
- 资源枚举规格
enum_spec = ('users', 'list', None),即调用 Graph API 的GET /v1.0/users; get_graph_resources()方法显式通过$select请求字段白名单:id, displayName, userPrincipalName, mail, accountEnabled, createdDateTime, jobTitle, department, userType——这正是示例策略中department、accountEnabled字段能够被value过滤器直接引用的前提;源码注释也说明userType默认不返回,必须显式选择才能用于访客用户过滤;- 读取用户需要
User.Read.All权限,代码在遇到 "Insufficient privileges" 或 403 时会记录明确的权限缺失日志并返回空列表; - 资源还预计算了
c7n:LastSignInDays、c7n:IsHighPrivileged、c7n:PasswordAge等以c7n:前缀标注的派生字段,供last-sign-in、password-age等过滤器使用,但这不影响本示例对原生字段的筛选。
value 过滤器底层:JMESPath 取值与操作符
示例中的两个过滤器都是通用 value 过滤器(ValueFilter,定义于 c7n/filters/core.py)。其工作原理是:用 key 作为 JMESPath 表达式在资源对象上取值,再与 value 按 op(默认为 eq/equal)比较。key: department 即读取用户对象上的 department 属性。
当 op 未显式写出时,默认使用相等比较。ValueFilter 支持的操作符全集定义在 c7n/filters/core.py 的 OPERATORS 字典中,包括:eq/equal、ne/not-equal、gt/greater-than、ge/gte、le/lte、lt/less-than、glob、regex/regex-case、in/ni/not-in、contains、difference、intersect、mod。因此同样一条策略可以轻松改造成「排除 IT 部门」(op: ne)、「按正则匹配部门」(op: regex)等变体。
策略中两个过滤器并列出现,在 Cloud Custodian 中默认按 and 逻辑串联:资源必须同时满足「账号已启用」与「部门为 IT」两个条件。若需要「或」语义,可用 or 块将过滤器分组。
运行策略:认证、命令与输出
运行示例策略前,需要先安装 c7n_azure 提供方并完成 Azure 认证(az login 或环境变量方式,详见 Azure 认证文档)。随后在包含策略 YAML 的目录下执行:
custodian run --output-dir=. custodian.yml
成功执行后,终端会输出类似下面的日志(格式参考 Azure 入门文档):
custodian.policy:INFO Running policy it-department-users resource: azure.entraid-user
custodian.policy:INFO policy: it-department-users resource:azure.entraid-user has count:N time:...
同时在输出目录下生成以策略名命名的目录,内含运行日志与 resources.json。resources.json 保存了筛选后的原始用户数据,是核对字段与调试策略的第一手资料。若想以更易读的形式查看结果,可使用 report 子命令:
custodian report --output-dir=. --format grid --field name=displayName --field department=department custodian.yml
--field 的格式为 --field 表头=JMESPath字段,例如上例会把 displayName 与 department 作为两列输出,便于人工核对该策略是否真的只命中了 IT 部门用户。
扩展:从「查询」到「治理」的进阶路径
按部门筛选本身是只读查询,而 Cloud Custodian 的价值在于把查询结果继续交给动作处理。EntraIDUser 类(tools/c7n_azure/c7n_azure/resources/entraid_user.py)为这一资源注册了以下过滤器与动作,可用于把本示例扩展成完整的身份治理策略:
| 类型 | 名称 | 说明 | 所需权限 |
|---|---|---|---|
| 过滤器 | value |
按任意用户字段(含 department、jobTitle、userType 等)筛选 |
User.Read.All |
| 过滤器 | auth-methods |
按已注册的认证方法筛选(如是否配置 Authenticator) | UserAuthenticationMethod.Read.All |
| 过滤器 | risk-level |
按 Identity Protection 风险级别筛选(none/low/medium/high) | IdentityRiskyUser.Read.All |
| 过滤器 | last-sign-in |
按最近登录天数筛选 | 需登录活动数据 |
| 过滤器 | group-membership |
按组成员关系筛选(match: any/all) |
GroupMember.Read.All 或 Directory.Read.All |
| 过滤器 | password-age |
按密码年龄筛选 | 需密码变更日期数据 |
| 动作 | disable |
通过 Graph API PATCH 将 accountEnabled 置为 false 禁用用户 |
User.ReadWrite.All |
| 动作 | require-mfa |
检查用户 MFA 方法配置情况并输出建议(不直接强制) | UserAuthenticationMethod.Read.All |
例如,将本示例与「90 天未登录」结合,即可形成「IT 部门 90 天未登录账号自动禁用」的治理策略;与 综合用户安全审计示例 中的访客用户审计(userType: Guest + accountEnabled: true,对应 CIS Azure 1.2)、密码老化(password-age + days: 180)等模式组合,可覆盖大部分 Entra ID 身份安全场景。c7n_azure 的 Entra ID 资源族(tools/c7n_azure/c7n_azure/resources/entraid.py)还包含组、组织、条件访问策略、安全默认值等资源,可按同样模式编写策略。
从源码结构看,该实现刻意遵循最小权限原则:tools/c7n_azure/c7n_azure/graph_utils.py 中维护了 Graph API 端点与所需权限的显式映射表(GRAPH_ENDPOINT_PERMISSIONS),未映射的端点会直接抛错而非回退到过宽的 .default 权限,避免服务主体被授予超出必要范围的访问权。在为策略配置 Azure AD 应用权限时,可对照上述表格按需勾选。