tfsec 检查规则详解:azure-keyvault-specify-network-acl 与 Azure Key Vault 网络 ACL 加固

原创2026-10-14 19:13:381,938 阅读
文章标签:应用安全SASTIaC

tfsec 检查规则详解:azure-keyvault-specify-network-acl 与 Azure Key Vault 网络 ACL 加固

Azure Key Vault 是云上集中托管密钥、证书与机密的核心服务,一旦缺失网络访问控制,任何能够触达服务端点的请求都可能尝试访问你的敏感数据。tfsec 内置的 azure-keyvault-specify-network-acl 检查(旧 ID 为 AZU020)用于在 Terraform 代码评审阶段强制要求 azurerm_key_vault 资源显式声明 network_acls 块,并将默认动作设为拒绝(Deny)。阅读本文后,你将掌握该检查的判定逻辑、正确与错误的 Terraform 写法、如何结合 tfsec 命令行与配置文件对 Key Vault 网络 ACL 进行加固,以及在实际项目中如何忽略、迁移或调整该检查的严重级别。

检查概览:规则身份与默认严重级别

在 tfsec 的规则体系中,该检查的完整身份信息如下,可在 rules.md 中核实:

维度 取值
规则 ID azure-keyvault-specify-network-acl
历史遗留 ID AZU020(见 internal/pkg/legacy/map.go)
Provider azure
Service keyvault
默认严重级别 critical
规则描述 Key vault should have the network acl block specified

critical 意味着该问题在 tfsec 的严重级别体系中属于最高等级(tfsec 的级别梯度为 CRITICAL > HIGH > MEDIUM > LOW),一旦出现默认即会在扫描结果中被突出显示,并可作为 CI 阻断发布的条件。值得注意的是,同目录下的 docs/checks/azure/keyvault/index.md 显示 Key Vault 相关的检查共有五条,其余四条(如 azure-keyvault-no-purge、azure-keyvault-ensure-secret-expiry 等)的默认严重级别多为 medium,这从侧面反映出网络暴露风险在 Key Vault 场景中被判定为最高优先级。

为什么要为 Key Vault 设置网络 ACL

Azure Key Vault 是凭据与密钥的存储端点,其默认网络行为是允许来自所有 IP 地址的访问。在没有网络 ACL 的情况下,只要请求携带了正确的认证信息(或利用了其他身份泄露路径),攻击者即可从任意位置访问 vault,正如检查文档中"Possible Impact"一节所述:

Without a network ACL the key vault is freely accessible

network_acls 块的作用是将风险暴露面收敛到可控范围:

  • 通过 default_action = "Deny",任何未命中的来源请求都会被拒绝;
  • 通过 bypass 允许受信任的 Azure 服务(如 AzureServices)在必要时绕过规则,保证平台服务(如 VM 磁盘加密、应用服务引用密钥)仍可正常工作;
  • 通过 ip_rules 与 virtual_network_subnet_ids 精确放行指定公网 IP 与 VNet 子网。

该检查的判定对象是 azurerm_key_vault 资源:如果资源定义中没有出现 network_acls 块,规则即判失败;只有显式声明了 network_acls 块(且默认动作合理)才会通过。

不安全的写法:缺失 network_acls 块

以下 Terraform 配置未声明 network_acls,因此必然无法通过 azure-keyvault-specify-network-acl 检查。它来自检查文档的"Insecure Example",是 tfsec 判定失败的标准样例:

resource "azurerm_key_vault" "bad_example" {
    name                        = "examplekeyvault"
    location                    = azurerm_resource_group.bad_example.location
    enabled_for_disk_encryption = true
    soft_delete_retention_days  = 7
    purge_protection_enabled    = false
}

即使该资源启用了软删除、设置了保留期等其他安全属性,只要缺少 network_acls 块,tfsec 就会报告为 critical 级别的违规。

安全的写法:显式声明并收紧 network_acls

检查文档的"Secure Example"给出了推荐配置——在资源内声明 network_acls 块,并同时设置 bypass 与 default_action:

resource "azurerm_key_vault" "good_example" {
    name                        = "examplekeyvault"
    location                    = azurerm_resource_group.good_example.location
    enabled_for_disk_encryption = true
    soft_delete_retention_days  = 7
    purge_protection_enabled    = false

    network_acls {
        bypass = "AzureServices"
        default_action = "Deny"
    }
}

对照两组样例可以发现:两者唯一的结构性差异就是 network_acls 块是否存在。这正是该检查的核心逻辑——要求网络访问控制成为 Key Vault 声明的"必备项"而非可选项。

network_acls 块关键参数与取值说明

为了让加固方案真正可落地,这里结合 azurerm provider 的常见用法补充说明 network_acls 内各参数的语义(以下为通用配置实践,tfsec 规则本身只要求块存在且默认动作合理):

参数 含义 常用取值 说明
default_action 未命中任何规则时的默认动作 Deny(推荐)/ Allow 检查文档明确指出默认动作应设为 Deny,这是通过本检查的关键;若设为 Allow,即使声明了 ACL 块,风险收敛效果也会大打折扣
bypass 允许绕过 ACL 的流量来源 AzureServices、None、AzureServices, AzureActiveDirectory 等 检查文档明确允许"Azure services can be allowed to bypass",因此在安全示例中采用了 AzureServices,用于放行平台托管的可信服务
ip_rules 允许访问的公网 IP 或 CIDR 列表 如 ["10.0.0.0/16"] 仅当默认动作为 Deny 时才有实际意义,用于显式放行白名单网段
virtual_network_subnet_ids 允许访问的 VNet 子网 ID 列表 如 [azurerm_subnet.example.id] 通过 VNet 集成限制访问来源,是比公网 IP 白名单更推荐的收敛方式

一个更完整的生产示例大致形如:

resource "azurerm_key_vault" "example" {
  name                       = "secure-example-keyvault"
  location                   = azurerm_resource_group.example.location
  tenant_id                  = data.azurerm_client_config.current.tenant_id
  sku_name                   = "standard"
  soft_delete_retention_days = 7
  purge_protection_enabled   = true

  network_acls {
    default_action             = "Deny"
    bypass                     = "AzureServices"
    ip_rules                   = ["203.0.113.0/24"]
    virtual_network_subnet_ids = [azurerm_subnet.example.id]
  }
}

需要强调的是,network_acls 块各参数的取值范围与联动规则属于 azurerm provider 的能力范畴,terraform 在 apply 阶段会进行二次校验;tfsec 的静态检查只负责在代码评审阶段尽早发现问题,两者相互补充。

在真实项目中运行该检查

tfsec 以目录为扫描单元,未指定目录时默认扫描当前目录(见 README.md)。进入包含上述 Terraform 文件的目录后直接运行:

tfsec .

如果文件中存在 bad_example 那样的 Key Vault 声明,tfsec 会在输出中列出 azure-keyvault-specify-network-acl 的 critical 级结果,并给出问题所在的行号。由于该规则默认级别为 critical,可以使用最小严重级别参数过滤掉低优先级噪声,只保留高危及以上问题:

tfsec --minimum-severity CRITICAL .

该参数的合法性校验实现在 internal/app/tfsec/cmd/flags.go,仅接受 CRITICAL、HIGH、MEDIUM、LOW 四个取值。在 CI 中通常还会配合 --soft-fail(见同一文件的 flags.go)来控制失败时的退出码行为。

需要豁免时的三种受支持方式

网络 ACL 的收紧并不适用于所有场景(例如完全托管于私有网络内的专用 vault,或团队明确评估过风险后希望临时放行)。tfsec 为这类情况提供了官方支持的豁免途径:

1. 行内注释忽略:在违规行或资源块上方添加 tfsec:ignore 注释。完整语法说明见 docs/guides/configuration/ignores.md:

resource "azurerm_key_vault" "example" {
  #tfsec:ignore:azure-keyvault-specify-network-acl
  name                        = "examplekeyvault"
  location                    = azurerm_resource_group.example.location
  enabled_for_disk_encryption = true
}

忽略注释还支持过期时间与工作区限定,例如 #tfsec:ignore:AZU020:exp:2026-12-31 表示仅在 2026-12-31 之前生效,之后自动重新启用——非常适合"临时豁免、限期复核"的场景。

2. 配置文件排除:tfsec 支持通过 .tfsec/config.yml(或 --config-file 指定的文件)以 exclude 列表排除检查,详见 docs/guides/configuration/config.md:

---
exclude:
  - azure-keyvault-specify-network-acl

3. 严重级别覆盖:若不想完全排除,而是希望降低该问题在结果中的权重(例如从 critical 降为 low),可以使用 severity_overrides,参考 docs/guides/configuration/config.md 与示例配置 _examples/custom/tfsec.yaml:

---
severity_overrides:
  azure-keyvault-specify-network-acl: LOW

历史 ID 兼容:从 AZU020 到新 ID

如果你在旧版本 tfsec 的配置或忽略注释中使用了 AZU020,无需手工逐个替换。仓库内 internal/pkg/legacy/map.go 维护了从旧 ID 到新 ID 的完整映射表(其中第 116 行正是 "AZU020": "azure-keyvault-specify-network-acl"),而 internal/pkg/ignores/migration.go 实现了自动化迁移:它会遍历指定目录中的 .tf 文件,将 tfsec:ignore:([A-Z]{3}\d{3}) 形式的旧 ID 重写为新 ID,并输出迁移统计。直接运行:

tfsec --migrate-ignores .

即可把代码中的 AZU020 等旧式忽略码批量迁移为 azure-keyvault-specify-network-acl 形式,保证新旧工具链的规则引用一致。

小结

azure-keyvault-specify-network-acl 是一条默认 critical 级别的 Azure 静态检查规则,其判定逻辑简洁而明确:azurerm_key_vault 资源必须声明 network_acls 块,且默认动作应设为 Deny,bypass 可保留给可信 Azure 服务。在代码评审阶段落实这一要求,可以把 Key Vault 的访问面收敛到白名单与 VNet 范围内,避免 vault 处于"全网可达"的暴露状态。同时,tfsec 的忽略、排除、严重级别覆盖与旧 ID 迁移机制,让这条规则在复杂项目与历史代码库中也能平滑落地、按需调整。

延伸阅读:本文讨论的规则登记表见 rules.md;同主题的 Azure 存储账户默认动作拒绝检查(azure-storage-default-action-deny)采用类似的"默认拒绝"思路,可参见 docs/checks/azure/storage/default-action-deny/index.md;Key Vault 系列其余检查汇总在 docs/checks/azure/keyvault/index.md。

登录后查看全文
tfsec