企业官网建设流程全解析

• 应用安全
• SAST
• IaC

导读

本文深入解析 tfsec 内置检查项azure-keyvault-no-purge（旧版 ID：AZU021）：当 Terraform 代码中的azurerm_key_vault未开启清除保护（purge protection）时，tfsec 将判定为 misconfiguration 并输出中等级别（medium）告警。文章将从检查原理、不安全/安全示例、CLI 与配置文件实践、忽略机制及文档生成机制五个层面展开，帮助开发者在写 Azure Key Vault 基础设施代码时主动规避密钥被永久清除的风险，并掌握 tfsec 中同类检查的使用与治理方法。

检查项概览

azure-keyvault-no-purge是 tfsec 为 Azure 云提供商注册的内置检查，其基本信息可以在 rules.md 中看到：

在旧版 ID 映射中，该检查对应AZU021，映射关系定义于 internal/pkg/legacy/map.go：

"AZU021": "azure-keyvault-no-purge",

该检查的默认严重级别为medium（中危），对应文档页面 docs/checks/azure/keyvault/no-purge/index.md。

为什么需要清除保护

根据检查文档 Explanation 部分，核心事实如下：

• 清除保护（Purge Protection）是 Azure Key Vault 的可选行为，默认不启用；
• 清除保护只能在软删除（soft-delete）已启用的前提下开启，二者是递进关系；
• 它可以通过 Azure CLI 或 PowerShell 开启。

风险影响

检查文档的 Possible Impact 明确指出：

Keys could be purged from the vault without protection

即：未开启清除保护时，密钥可能在没有保护的情况下被永久清除（purge），且清除后不可恢复。这与软删除形成鲜明对比——软删除允许在保留期内恢复被删除的对象，而 purge 是彻底销毁。因此，对于密钥、证书、机密等关键资产，缺少清除保护意味着运维误操作或恶意操作可能导致不可逆的数据丢失。

不安全示例：触发检查

以下 Terraform 配置定义了一个未开启清除保护的 Key Vault，tfsec 会判定其不通过（fail）azure-keyvault-no-purge检查：

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

关键点：purge_protection_enabled = false或完全省略该参数，都会使检查失败。文档还特别强调，仅设置purge_protection_enabled为true还不够，还需要先满足软删除的前提条件（见下文安全示例中的soft_delete_retention_days）。

安全示例：通过检查

修复方式是在 Key Vault 资源上同时开启软删除与清除保护：

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 = true }

该示例对应检查文档中的 Secure Example，其通过检查的关键是：

• soft_delete_retention_days = 7：显式声明软删除保留期（清除保护只能在软删除启用后开启）；
• purge_protection_enabled = true：开启清除保护。

进一步加固：组合其他 Key Vault 检查

清除保护并非 Key Vault 安全加固的全部。tfsec 的 Azure keyvault 服务下还注册了 4 个关联检查，完整清单见 docs/checks/azure/keyvault/index.md：

• content-type-for-secret：Key Vault Secret 应设置 content type；
• ensure-key-expiry：所有密钥应设置过期时间；
• ensure-secret-expiry：Key Vault Secret 应设置过期时间；
• specify-network-acl：Key Vault 应配置 network ACL 块（默认严重级别为critical）。

例如，在安全示例的基础上叠加网络访问控制，可同时通过多个检查（参考 specify-network-acl 安全示例）：

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 = true network_acls { bypass = "AzureServices" default_action = "Deny" } }

在 tfsec 中运行与验证

基础运行

tfsec 默认扫描当前目录（README 使用说明）：

tfsec .

非零退出码表示发现了问题。针对上述 bad_example 配置，运行结果会输出azure-keyvault-no-purge中危告警及对应代码行。

也可以使用 Docker 运行（README Docker 用法）：

docker run --rm -it -v "$(pwd):/src" aquasec/tfsec /src

聚焦该检查的输出

如果只想关注azure-keyvault-no-purge，可以使用--filter-results参数（定义于 internal/app/tfsec/cmd/flags.go）：

tfsec --filter-results azure-keyvault-no-purge .

按严重级别过滤

默认情况下所有严重级别的结果都会输出。可以通过--minimum-severity（短参数-m）只报告 MEDIUM 及以上结果（flags.go 参数定义）：

tfsec -m MEDIUM .

该参数只接受CRITICAL、HIGH、MEDIUM、LOW四个取值，非法值会直接报错（flags.go 校验逻辑）。

其他相关输出参数

完整参数清单见 docs/guides/usage.md，常用几个：

例如输出 SARIF 报告便于 CI 集成：

tfsec --format sarif --out result.sarif .

如何忽略该检查

当业务上确实需要临时关闭某个 Key Vault 的清除保护（例如迁移场景中的短期配置），可以在 HCL 中使用tfsec:ignore注释忽略该规则（README 忽略规则、docs/guides/configuration/ignores.md）：

resource "azurerm_key_vault" "example" { name = "examplekeyvault" location = azurerm_resource_group.example.location purge_protection_enabled = false #tfsec:ignore:azure-keyvault-no-purge }

忽略规则支持三种写法：行内注释、块上方独立注释、module 块上方（作用于模块内所有实例）。同时支持过期时间与 workspace 作用域：

#tfsec:ignore:azure-keyvault-no-purge:exp:2026-12-31 resource "azurerm_key_vault" "example" { ... }

带:exp:yyyy-mm-dd的忽略规则只在指定日期前生效，之后自动重新告警，避免“忽略后遗忘”的长期风险。

通过配置文件治理该检查

使用配置文件

tfsec 会自动加载扫描根路径下.tfsec目录中的config.json或config.yml，也可以通过--config-file显式指定（docs/guides/configuration/config.md）：

tfsec --config-file tfsec.yml .

覆盖严重级别

如果团队认为清除保护缺失应该被视为高危，可以在配置文件中使用severity_overrides提升该检查的严重级别（config.md Severity Overrides）：

--- severity_overrides: azure-keyvault-no-purge: HIGH

排除与最小严重级别

--- minimum_severity: MEDIUM exclude: - azure-keyvault-no-purge

其中exclude同样支持带过期时间的形式（如azure-keyvault-no-purge:2026-12-31），过期后自动重新启用（config.md Excluding checks）。配置解析逻辑由 internal/pkg/config/config.go 实现，支持 JSON 与 YAML 两种格式。

底层原理：检查文档从何而来

该检查文档并非手写，而是由 tfsec 的文档生成工具tfsec-docs从 defsec 规则注册表中自动生成。生成入口在 cmd/tfsec-docs/main.go，它遍历rules.GetRegistered()中所有带 Terraform 示例的规则，将规则的 Summary、Severity、Explanation、Impact、Resolution、BadExample、GoodExample、Links 等字段填充进页面模板（cmd/tfsec-docs/webpage.go 模板定义）。

这就是no-purge/index.md页面结构（Severity / Explanation / Possible Impact / Suggested Resolution / Insecure Example / Secure Example / Links）与模板字段一一对应的原因。因此，该页面的内容（包括两个 Terraform 示例和 medium 级别）直接反映了注册规则的真实定义。生成后的文档通过 mkdocs.yml 挂载到 mkdocs 站点，与 keyvault 系列其他检查共同构成 Azure 安全基线文档。

总结

azure-keyvault-no-purge检查解决的是一个高代价的不可逆风险：密钥被永久清除。它的实践要点可以浓缩为三条：

1. 写代码时：azurerm_key_vault上同时配置soft_delete_retention_days与purge_protection_enabled = true；
2. CI 中：将 tfsec 扫描纳入流水线，结合--minimum-severity、SARIF 输出等能力让 MEDIUM 级别的此类告警可见、可追踪；
3. 治理上：确有例外时使用带过期时间的tfsec:ignore或配置文件exclude显式豁免，并通过severity_overrides按团队规范调整级别。

对于 Key Vault 的完整加固，建议同时关注同属 keyvault 服务的specify-network-acl、ensure-key-expiry、ensure-secret-expiry与content-type-for-secret检查，共同构成纵深防御。

• 应用安全
• SAST
• IaC