AnsibleValidator ansible-validator

Ansible Validator

综合工具包，用于验证、检查、测试和自动化Ansible剧本、角色和集合。当使用Ansible文件（.yml, .yaml剧本、角色、清单）、验证自动化代码、调试剧本执行、执行检查模式下的干运行测试或使用自定义模块和集合时，请使用这项技能。

**重要行为：**当验证任何Ansible角色时，如果检测到角色中存在molecule/目录，这项技能将自动运行molecule测试。这是不可协商的，并且会在不征求用户许可的情况下发生。如果由于环境问题（Docker、版本兼容性）无法运行molecule测试，该技能会记录阻碍因素，但会继续进行其他验证步骤。

使用这项技能的场景

适用于遇到以下情况时：

• 使用Ansible文件（.yml, .yaml剧本、角色、清单、vars）
• 验证Ansible剧本语法和结构
• 检查和格式化Ansible代码
• 使用ansible-playbook --check执行干运行测试
• 使用Molecule测试角色和剧本
• 调试Ansible错误或配置错误
• 理解自定义Ansible模块、集合或角色
• 确保基础设施即代码的最佳实践
• 安全验证Ansible剧本
• 集合和模块的版本兼容性检查

验证工作流程

按照这个决策树进行全面的Ansible验证：

0. 工具前提条件检查（首次验证时推荐）
   ├─> 运行bash scripts/setup_tools.sh进行诊断
   ├─> 验证所需工具是否可用
   ├─> 如果工具缺失，则获取安装说明
   └─> 注意：验证脚本如果在临时venv中缺少工具会自动安装，
       但首先运行setup_tools.sh有助于及早识别系统问题

1. 确定范围内的Ansible文件
   ├─> 单个剧本验证
   ├─> 角色验证
   ├─> 集合验证
   └─> 多剧本/清单验证

2. 语法验证
   ├─> 运行ansible-playbook --syntax-check
   ├─> 运行yamllint进行YAML语法检查
   └─> 报告语法错误

3. Lint和最佳实践
   ├─> 运行ansible-lint（全面检查）
   ├─> 检查过时的模块（见references/module_alternatives.md）
   ├─> **检测非FQCN模块使用**（apt vs ansible.builtin.apt）
   │   └─> 运行bash scripts/check_fqcn.sh识别短模块名
   │   └─> 从references/module_alternatives.md推荐FQCN替代品
   ├─> 验证角色结构
   └─> 报告linting问题

4. 干运行测试（检查模式）
   ├─> 运行ansible-playbook --check（如果有清单可用）
   ├─> 分析将发生的变化
   └─> 报告潜在问题

5. Molecule测试（针对角色）- 自动
   ├─> 检查角色中是否存在molecule/目录
   ├─> 如果存在，则始终自动运行molecule测试
   ├─> 针对多个场景进行测试
   ├─> 报告测试结果（通过/失败/阻塞）
   └─> 如果测试无法运行，报告任何环境问题

6. 自定义模块/集合分析（如果检测到）
   ├─> 提取模块/集合信息
   ├─> 确定版本
   ├─> 查找文档（WebSearch或Context7）
   └─> 提供版本特定指导

7. 安全和最佳实践审查-需要双重扫描
   ├─> 运行bash scripts/validate_playbook_security.sh或validate_role_security.sh（Checkov）
   ├─> **还运行bash scripts/scan_secrets.sh**进行硬编码秘密检测
   │   └─> 这可以捕捉到Checkov可能遗漏的秘密（密码、API密钥、令牌）
   ├─> 验证权限提升
   ├─> 审查文件权限
   └─> 识别常见反模式

8. 参考文档-必须咨询
   ├─> **必须阅读** references/common_errors.md当检测到任何错误时
   │   └─> 提取特定于错误类型的补救步骤
   │   └─> 在验证报告中包括相关指导
   ├─> **必须阅读** references/best_practices.md当检测到警告时
   │   └─> 引用具体的的最佳实践建议
   ├─> **必须阅读** references/module_alternatives.md当：
   │   └─> 检测到过时的模块
   │   └─> 使用了非FQCN模块名称（apt、service等）
   │   └─> 提供具体的FQCN迁移建议
   └─> **必须阅读** references/security_checklist.md当发现安全问题时
       └─> 包括来自清单的具体补救指导

**关键：参考文件不是可选的。**当检测到问题时，必须阅读相应的参考文件，并将其实现在向用户提供可操作的补救步骤。仅仅提及参考文件路径是不够的-必须查阅内容并提取相关指导。

核心能力

1. YAML语法验证

**目的：**在Ansible解析之前确保YAML文件在语法上是正确的。

工具：

• yamllint - YAML语法和格式化的linter
• ansible-playbook --syntax-check - Ansible特定的语法验证

工作流程：

# 使用yamllint检查YAML语法
yamllint playbook.yml

# 或者针对整个目录
yamllint -c .yamllint .

# 检查Ansible剧本语法
ansible-playbook playbook.yml --syntax-check

常见问题：

• 缩进错误
• 无效的YAML语法
• 重复的键
• 尾随空白
• 行长度违规
• 缺少冒号或引号

最佳实践：

• 在ansible-lint之前始终运行yamllint
• 一致地使用2个空格缩进
• 在.yamllint中配置yamllint规则
• 首先修复YAML语法错误，然后解决Ansible特定问题

2. Ansible Lint

**目的：**执行Ansible最佳实践并捕获常见错误。

工作流程：

# 检查单个剧本
ansible-lint playbook.yml

# 检查目录中的所有剧本
ansible-lint .

# 使用特定规则检查
ansible-lint -t yaml,syntax playbook.yml

# 跳过特定规则
ansible-lint -x yaml[line-length] playbook.yml

# 输出可解析格式
ansible-lint -f pep8 playbook.yml

# 显示规则详情
ansible-lint -L

常见问题：

• 过时的模块或语法
• 缺少任务名称
• 不当地使用command与shell
• 未引用的模板表达式
• 应为变量的硬编码值
• 缺少become指令
• 低效的任务模式
• Jinja2模板错误
• 变量使用不当
• 角色依赖问题

严重性级别：

• **错误：**必须修复-将导致失败
• **警告：**应该修复-潜在问题
• **信息：**考虑修复-最佳实践违规

自动修复方法：

• ansible-lint支持--fix自动修复问题
• 应用前始终审查更改
• 有些问题需要手动干预

3. 安全扫描（Checkov）

**目的：**使用Checkov这个静态代码分析工具，识别Ansible代码中的安全漏洞和合规违规行为。

Checkov提供除了ansible-lint之外的：

虽然ansible-lint侧重于代码质量和最佳实践，Checkov专门针对安全策略和合规性：

• **SSL/TLS安全：**证书验证实施
• **HTTPS实施：**确保下载使用安全协议
• **软件包安全：**软件包的GPG签名验证
• **云安全：**AWS、Azure、GCP配置错误检测
• **合规框架：**映射到安全标准
• **网络安全：**防火墙和网络策略验证

工作流程：

# 扫描剧本的安全问题
bash scripts/validate_playbook_security.sh playbook.yml

# 扫描整个目录
bash scripts/validate_playbook_security.sh /path/to/playbooks/

# 扫描角色的安全问题
bash scripts/validate_role_security.sh roles/webserver/

# 直接使用checkov
checkov -d . --framework ansible

# 扫描并使用特定输出格式
checkov -d . --framework ansible --output json

# 扫描并跳过特定检查
checkov -d . --framework ansible --skip-check CKV_ANSIBLE_1

常见安全问题：

证书验证：

• CKV_ANSIBLE_1： URI模块禁用证书验证
• CKV_ANSIBLE_2： get_url禁用证书验证
• CKV_ANSIBLE_3： yum禁用证书验证
• CKV_ANSIBLE_4： yum禁用SSL验证

HTTPS实施：

• CKV2_ANSIBLE_1： URI模块使用HTTP而不是HTTPS
• CKV2_ANSIBLE_2： get_url使用HTTP而不是HTTPS

软件包安全：

• CKV_ANSIBLE_5： apt安装软件包时没有GPG签名
• CKV_ANSIBLE_6： apt使用force参数绕过签名
• CKV2_ANSIBLE_4：* dnf安装软件包时没有GPG签名
• CKV2_ANSIBLE_5： dnf禁用SSL验证
• CKV2_ANSIBLE_6： dnf禁用证书验证

错误处理：

• CKV2_ANSIBLE_3： 块缺少错误处理

云安全（当管理云资源时）：

• CKV_AWS_88： 具有公共IP的EC2实例
• CKV_AWS_135： 没有EBS优化的EC2实例

示例违规：

# 糟糕-禁用证书验证
- name: 下载文件
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    validate_certs: false  # 安全问题！

# 良好-启用证书验证
- name: 下载文件
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    validate_certs: true  # 或省略（默认为true）

与验证工作流程的集成：

Checkov补充ansible-lint：

1. ansible-lint捕获代码质量问题、过时模块、最佳实践
2. Checkov捕获安全漏洞、合规违规、密码问题

**最佳实践：**运行两个工具进行全面验证：

# 完整的验证工作流程
bash scripts/validate_playbook.sh playbook.yml         # 语法+Lint
bash scripts/validate_playbook_security.sh playbook.yml  # 安全

输出格式：

Checkov提供清晰的安全扫描结果：

安全扫描结果：
  通过：  15个检查
  失败：  2个检查
  跳过： 0个检查

失败检查：
  检查： CKV_ANSIBLE_2 - "确保get_url没有禁用证书验证"
    资源：tasks/main.yml:download_file
    文件：/roles/webserver/tasks/main.yml:10-15

补救资源：

• Checkov策略索引：https://www.checkov.io/5.Policy Index/ansible.html
• Ansible安全清单：references/security_checklist.md
• Ansible最佳实践：references/best_practices.md

安装：

如果系统范围内不可用，则Checkov会在临时环境中自动安装。如需永久安装：

pip3 install checkov

何时使用：

• 在部署到生产环境之前
• 在CI/CD管道中进行自动化安全检查
• 处理敏感基础设施时
• 进行合规性审计和安全审查
• 下载文件或安装软件包时
• 使用Ansible管理云资源时

4. 剧本语法检查

**目的：**在不执行任务的情况下验证剧本语法。

工作流程：

# 基本语法检查
ansible-playbook playbook.yml --syntax-check

# 带清单的语法检查
ansible-playbook -i inventory playbook.yml --syntax-check

# 带额外变量的语法检查
ansible-playbook playbook.yml --syntax-check -e @vars.yml

# 检查所有剧本
for file in *.yml; do
  ansible-playbook "$file" --syntax-check
done

验证检查：

• YAML解析
• 剧本结构
• 任务定义
• 变量引用
• 模块参数语法
• Jinja2模板语法
• Include/import语句

错误处理：

• 解析错误消息以查找特定问题
• 检查模块名称的拼写错误
• 验证变量定义
• 确保适当的缩进
• 检查include/import的文件路径

5. 干运行测试（检查模式）

**目的：**预览实际应用之前将进行的更改。

工作流程：

# 以检查模式（干运行）运行
ansible-playbook -i inventory playbook.yml --check

# 检查模式带差异
ansible-playbook -i inventory playbook.yml --check --diff

# 检查模式带详细输出
ansible-playbook -i inventory playbook.yml --check -v

# 针对特定主机进行检查模式
ansible-playbook -i inventory playbook.yml --check --limit webservers

# 带标签的检查模式
ansible-playbook -i inventory playbook.yml --check --tags deploy

# 逐步执行任务
ansible-playbook -i inventory playbook.yml --check --step

检查模式分析：

当审查检查模式输出时，重点关注：

1. 任务更改：

   • ok：不需要更改
   • changed：将进行更改
   • failed：将失败（检查check_mode支持）
   • skipped：条件跳过

2. 差异输出：

   • 显示文件的确切更改
   • 帮助识别无意的修改
   • 审核模板更改非常有用

3. 处理程序：

   • 哪些处理程序会被通知
   • 将发生的服务重启
   • 潜在的停机时间

4. 失败的任务：

   • 有些模块不支持检查模式
   • 可能需要check_mode: no覆盖
   • 识别将失败的任务

限制：

• 并非所有模块都支持检查模式
• 有些任务依赖于之前的更改
• 可能无法准确反映所有更改
• 有状态的操作可能会显示意外的结果

安全考虑：

• 在实际执行之前始终运行检查模式
• 仔细审查差异输出
• 首先在非生产环境中测试
• 验证更改是否合理
• 检查无意的副作用

6. Molecule测试

**目的：**在隔离环境中使用多个场景测试Ansible角色。

**自动执行：**当验证任何带有molecule/目录的Ansible角色时，这项技能将自动运行molecule测试，使用bash scripts/test_role.sh <role-path>。这是强制性的，不会征求用户意见。

何时使用：

• 自动触发当验证带有molecule/目录的角色时
• 在部署前测试角色
• 验证角色在不同操作系统版本上的兼容性
• 复杂角色的集成测试
• CI/CD管道验证

工作流程：

# 为角色初始化molecule
cd roles/myrole
molecule init scenario --driver-name docker

# 列出场景
molecule list

# 运行完整的测试序列
molecule test

# 单独测试阶段
molecule create      # 创建测试实例
molecule converge    # 对实例运行Ansible
molecule verify      # 运行验证测试
molecule destroy     # 销毁测试实例

# 使用特定场景进行测试
molecule test -s alternative

# 调试模式
molecule --debug test

# 保留实例以供调试
molecule converge
molecule login       # SSH进入测试实例

测试序列：

1. dependency - 安装角色依赖
2. lint - 运行yamllint和ansible-lint
3. cleanup - 测试前的清理
4. destroy - 销毁现有实例
5. syntax - 运行语法检查
6. create - 创建测试实例
7. prepare - 准备实例（安装要求）
8. converge - 运行角色
9. idempotence - 再次运行，验证无更改
10. side_effect - 可选的副作用剧本
11. verify - 运行验证测试（Testinfra等）
12. cleanup - 最终清理
13. destroy - 销毁测试实例

Molecule配置：

检查molecule/default/molecule.yml：

dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
provisioner:
  name: ansible
verifier:
  name: ansible

验证测试：

Molecule支持多个验证器：

• Ansible（内置）：使用Ansible任务进行验证
• Testinfra：基于Python的基础设施测试
• Goss：基于YAML的服务器验证

示例Ansible验证器（molecule/default/verify.yml）：

---
- name: 验证
  hosts: all
  tasks:
    - name: 检查服务是否正在运行
      service:
        name: nginx
        state: started
      check_mode: true
      register: result
      failed_when: result.changed

常见Molecule错误：

• 驱动程序未安装（docker、podman、vagrant）
• 缺少Python依赖
• 平台镜像不可用
• 网络连接问题
• 驱动程序权限不足

7. 自定义模块和集合文档查找

**目的：**自动发现并检索自定义模块和集合的版本特定文档，使用网络搜索和Context7 MCP。

触发时：

• 遇到不熟悉的模块使用
• 使用自定义/私有集合
• 调试模块特定错误
• 了解新模块参数
• 检查版本兼容性
• 过时模块的替代品

检测工作流程：

1. 提取模块信息：

   • 使用scripts/extract_ansible_info_wrapper.sh解析剧本和角色
   • 识别模块使用和集合
   • 从requirements.yml提取版本约束

2. 提取集合信息：

   • 识别集合命名空间（例如community.general、ansible.posix）
   • 从requirements.yml或galaxy.yml确定集合版本
   • 检测自定义/私有与公共集合

文档查找策略：

对于公共Ansible集合（例如community.general、ansible.posix、cisco.ios）：

# 使用Context7 MCP获取版本特定文档
# 示例：community.general集合版本5.0

步骤：

1. 使用mcp__context7__resolve-library-id和集合名称
2. 使用mcp__context7__get-library-docs获取文档
3. 根据需要关注特定模块或插件

对于自定义/私有模块或集合：

# 使用WebSearch查找文档
# 包括版本在搜索查询中

步骤：

1. 使用模块/集合名称+版本构建搜索查询
2. 使用WebSearch工具进行有针对性的查询
3. 优先考虑官方文档来源
4. 提取相关示例和使用模式

搜索查询模板：

# 自定义模块
"[module-name] ansible module version [version] documentation"
"[module-name] ansible [module-type] example"
"ansible [collection-name].[module-name] parameters"

# 自定义集合
"ansible collection [collection-name] version [version]"
"[collection-namespace].[collection-name] ansible documentation"
"ansible galaxy [collection-name] modules"

# 特定错误
"ansible [module-name] error: [error-message]"
"ansible [collection-name] module failed"

示例工作流程：

用户使用：community.docker.docker_container版本3.0.0

1. 从剧本中提取模块信息：
   tasks:
     - name: 启动容器
       community.docker.docker_container:
         name: myapp
         image: nginx:latest

2. 检测集合：community.docker

3. 搜索文档：
   - 尝试Context7：mcp__context7__resolve-library-id("ansible community.docker")
   - 如果找到，使用get-library-docs获取docker_container模块
   - 如果未找到，使用WebSearch："ansible community.docker collection version 3.0 docker_container module documentation"

4. 如果找到官方文档：
   - 解析模块参数（必需vs可选）
   - 识别返回值
   - 找到使用示例
   - 检查版本兼容性

5. 向用户提供版本特定指导

版本兼容性检查：

• 比较所需集合版本与可用版本
• 识别过时的模块或参数
• 如果使用过时版本，建议升级路径
• 警告不同版本之间的破坏性更改
• 检查Ansible核心版本兼容性

常见集合来源：

• Ansible Galaxy：官方社区集合
• Red Hat Automation Hub：认证集合
• GitHub：自定义/私有集合
• 内部仓库：公司特定的集合

8. 安全和最佳实践验证

**目的：**识别Ansible剧本中的安全漏洞和反模式。

安全检查：

1. 秘密检测：

   # 检查硬编码的凭据
   grep -r "password:" *.yml
   grep -r "secret:" *.yml
   grep -r "api_key:" *.yml
   grep -r "token:" *.yml
   

   **补救：**使用Ansible Vault、环境变量或外部秘密管理

2. 权限提升：

   • 不必要的become: yes使用
   • 缺少become_user指定
   • 过度的sudo规则
   • 以root身份运行整个剧本

3. 文件权限：

   • 世界可读的敏感文件
   • 文件/模板任务缺少mode参数
   • 错误的所有权设置
   • 敏感文件未用vault加密

4. 命令注入：

   • 未经验证的变量在shell/command模块中
   • 用户输入缺少quote过滤器
   • 直接在命令字符串中使用{{ var }}

5. 网络安全：

   • 未加密的协议（HTTP而不是HTTPS）
   • 缺少SSL/TLS验证
   • 在0.0.0.0上暴露服务
   • 不安全的默认端口

最佳实践：

1. 剧本组织：

   • 逻辑任务分离
   • 用于常见模式的可重用角色
   • 清晰的目录结构
   • 有意义的剧本名称

2. 变量管理：

   • 敏感数据使用Vault加密
   • 清晰的变量命名约定
   • 变量优先级意识
   • 组/主机vars组织
   • 使用default()过滤器设置默认值

3. 任务命名：

   • 描述性任务名称
   • 一致的命名约定
   • 面向行动的描述
   • 在名称中包含更改的资源

4. 幂等性：

   • 所有任务应该是幂等的
   • 使用适当的模块而不是command/shell
   • 检查模式兼容性
   • 正确使用creates、removes用于command任务
   • 除非必要，否则避免使用changed_when: false

5. 错误处理：

   • 使用failed_when自定义失败条件
   • 实施block/rescue/always错误恢复
   • 设置适当的any_errors_fatal
   • 谨慎使用ignore_errors

6. 文档：

   • 每个角色的README
   • defaults/main.yml中的变量文档
   • meta/main.yml中的角色元数据
   • 剧本头部注释

参考文档：

有关详细的安全指南和最佳实践，请参考：

• references/security_checklist.md - 常见安全漏洞
• references/best_practices.md - Ansible编码标准
• references/common_errors.md - 常见错误和解决方案

工具前提条件

验证之前检查所需工具：

# 检查Ansible安装
ansible --version
ansible-playbook --version

# 检查ansible-lint安装
ansible-lint --version

# 检查yamllint安装
yamllint --version

# 检查molecule安装（角色测试）
molecule --version

# 安装缺失的工具（例如pip）
pip install ansible ansible-lint yamllint ansible-compat

# 安装带有docker驱动程序的molecule
pip install molecule molecule-docker

最低版本：

• Ansible：>= 2.9（建议>= 2.12）
• ansible-lint：>= 6.0.0
• yamllint：>= 1.26.0
• molecule：>= 3.4.0（如果测试角色）

可选工具：

• ansible-inventory - 清单验证和图形化
• ansible-doc - 模块文档查找
• jq - JSON解析用于结构化输出

错误排除

常见错误和解决方案

错误：模块未找到

解决方案：使用ansible-galaxy安装所需集合
检查collections/requirements.yml
验证集合命名空间和名称

错误：未定义变量

解决方案：在vars、defaults或group_vars中定义变量
检查变量优先级
使用default()过滤器用于可选变量
验证变量文件是否已包含

错误：模板语法错误

解决方案：检查Jinja2模板语法
验证变量类型与过滤器匹配
确保正确的引号转义
单独测试模板渲染

错误：连接失败

解决方案：验证清单主机可访问性
检查SSH配置和密钥
验证ansible_host和ansible_port
使用ansible -m ping进行测试

错误：权限被拒绝

解决方案：为权限提升添加become: yes
验证sudo/su配置
检查文件权限
验证用户具有必要权限

错误：过时模块

解决方案：检查ansible-lint输出以获取替代品
查阅模块文档以获取替代品
更新为推荐模块
测试新模块的功能

资源

scripts/

setup_tools.sh - 检查所需的Ansible验证工具，并提供安装说明。

用法：

bash scripts/setup_tools.sh

extract_ansible_info_wrapper.sh - Bash包装器extract_ansible_info.py，自动处理PyYAML依赖。如果系统Python中没有PyYAML，则创建临时venv。

用法：

bash scripts/extract_ansible_info_wrapper.sh <path-to-playbook-or-role>

输出：具有模块、集合和版本的JSON结构

extract_ansible_info.py - Python脚本（由包装器调用），解析Ansible剧本和角色以提取模块使用情况、集合依赖项和版本信息。包装器脚本自动处理依赖管理。

validate_playbook.sh - 综合验证脚本，运行语法检查、yamllint和ansible-lint。如果系统上没有ansible和ansible-lint，则自动在临时venv中安装（首选系统版本）。

用法：

bash scripts/validate_playbook.sh <playbook.yml>

validate_playbook_security.sh - 使用Checkov扫描剧本的安全漏洞。如果系统上没有checkov，则自动在临时venv中安装。补充validate_playbook.sh，专注于安全特定检查，如SSL/TLS验证、HTTPS实施和软件包签名验证。

用法：

bash scripts/validate_playbook_security.sh <playbook.yml>
# 或扫描整个目录
bash scripts/validate_playbook_security.sh /path/to/playbooks/

validate_role.sh - 综合角色验证脚本，检查角色结构、YAML语法、Ansible语法、linting和molecule配置。

用法：

bash scripts/validate_role.sh <role-directory>

验证：

• 角色目录结构（必需和建议的目录）
• 每个目录中所需的main.yml文件
• 使用yamllint进行YAML语法检查
• 使用ansible-playbook进行Ansible语法检查
• 使用ansible-lint进行最佳实践检查
• 分子测试配置（如果存在）

validate_role_security.sh - 使用Checkov对Ansible角色进行安全验证。扫描整个角色目录以查找安全问题。如果系统上没有checkov，则自动在临时venv中安装。补充validate_role.sh，进行安全重点检查。

用法：

bash scripts/validate_role_security.sh <role-directory>

test_role.sh - 分子测试包装器脚本，自动安装依赖项。如果未安装molecule，则自动创建临时venv、安装molecule和依赖项、运行测试和清理。

用法：

bash scripts/test_role.sh <role-directory> [scenario]

scan_secrets.sh - 综合秘密扫描器，使用基于grep的模式匹配在Ansible文件中检测硬编码的秘密。补充Checkov安全扫描，捕捉静态分析可能遗漏的秘密，包括密码、API密钥、令牌、AWS凭据和私钥。

用法：

bash scripts/scan_secrets.sh <playbook.yml|role-directory|directory>

检测：

• 硬编码的密码和凭据
• API密钥和令牌
• AWS访问密钥和秘密密钥
• 包含嵌入式凭据的数据库连接字符串
• 私钥内容（RSA、OpenSSH、EC、DSA）

**重要：**此脚本应始终与Checkov（validate_*_security.sh）一起运行，进行全面安全扫描。Checkov捕获SSL/TLS和协议问题；此脚本捕获硬编码的秘密。

check_fqcn.sh - 扫描Ansible文件，识别使用短名称而不是完全限定集合名称（FQCN）的模块。建议迁移到ansible.builtin.*或适当的集合命名空间，以获得更好的清晰度和未来的兼容性。

用法：

bash scripts/check_fqcn.sh <playbook.yml|role-directory|directory>

检测：

• ansible.builtin模块（apt、yum、copy、file、template、service等）
• community.general模块（ufw、docker_container、timezone等）
• ansible.posix模块（synchronize、acl、firewalld等）

提供具体的迁移建议和FQCN替代品。

references/

security_checklist.md - Ansible剧本的全面安全验证清单，涵盖秘密管理、权限提升、文件权限和命令注入。

best_practices.md - Ansible编码标准和最佳实践，包括剧本组织、变量处理、任务命名、幂等性和文档。

common_errors.md - 常见Ansible错误的数据库，附有详细的解决方案和预防策略。

module_alternatives.md - 替换过时模块的指南。

assets/

.yamllint - Ansible YAML文件的预配置yamllint规则。

.ansible-lint - 预配置的ansible-lint配置，具有合理的规则设置。

molecule.yml.template - 角色测试的分子配置模板。

工作流示例

示例1：验证单个剧本

用户："检查这个playbook.yml文件是否有效"

步骤：
1. 阅读文件以了解内容
2. 对文件运行yamllint
3. 运行ansible-playbook --syntax-check
4. 运行ansible-lint
5. 报告发现的任何问题
6. 如果检测到自定义模块，查找文档
7. 如有需要，提出修复建议

示例2：验证Ansible角色

用户："验证我的ansible角色在./roles/webserver/"

步骤：
1. 运行bash scripts/validate_role.sh ./roles/webserver/
2. 这自动检查：
   - 角色目录结构（tasks/, defaults/, handlers/, meta/等）
   - 必需的main.yml文件
   - 使用yamllint进行YAML语法检查
   - 使用ansible-playbook进行Ansible语法检查
   - 使用ansible-lint进行最佳实践检查
   - 分子测试配置（如果存在）
3. 报告发现的任何问题（错误和警告）
4. 如果检测到自定义模块，查找文档
5. 提供具体的修复建议
6. **关键：**如果角色中存在molecule/目录，则自动运行分子测试：
   - 运行bash scripts/test_role.sh ./roles/webserver/
   - 不要事先征求用户意见-molecule测试对于配置了它的