摘要 Excerpt:

本文介绍如何通过 Ansible + HashiCorp Vault + GitLab CI 实现 Linux 账号密码自动轮换。方案支持定时触发、按环境过滤、远端密码修改后校验、成功后写入 Vault,并生成审计报告。文章还重点记录了 Vault HTTPS 证书校验失败的排查过程和 VAULT_CACERT 的正确配置方式。


背景:为什么要做密码自动轮换

在传统运维场景中,Linux 服务器上的业务账号密码经常存在几个问题:

  • 密码长期不变,安全风险越来越高。
  • 手工修改密码容易遗漏主机。
  • 修改后没有统一的记录和审计。
  • 密码保存方式不规范,容易散落在文档、聊天记录或个人本地。
  • 一旦批量修改失败,很难判断哪些主机成功、哪些主机失败。

这次要解决的是一个具体场景:批量轮换 Linux 主机上的 dev 账号密码,并将轮换成功后的密码托管到 HashiCorp Vault。

整体目标很明确:

每台主机单独生成随机密码,远端确认修改成功后,才把新密码写入 Vault。失败主机不更新 Vault,避免 Vault 中保存和真实服务器不一致的密码。

最终方案使用三部分组合完成:

  • Ansible:负责连接目标主机、修改 Linux 账号密码、读取 /etc/shadow 做结果校验。
  • HashiCorp Vault:负责保存最终密码,作为统一的密码托管中心。
  • GitLab CI:负责定时触发任务、传入 Vault 凭据、收集执行报告。

整体架构思路

这套方案不是简单地“生成密码然后写入 Vault”,而是强调一个关键原则:

先确认远端密码真的改成功,再写 Vault。

完整流程如下:

GitLab CI 定时触发
        |
        v
使用 AppRole 登录 Vault,获取短期 VAULT_TOKEN
        |
        v
执行 Ansible Playbook
        |
        v
检查目标主机是否存在 dev 账号
        |
        v
控制端生成随机密码和 SHA-512 shadow hash
        |
        v
Ansible user 模块修改远端密码
        |
        v
读取远端 /etc/shadow 校验 hash 是否一致
        |
        v
校验成功后写入 Vault KV v2
        |
        v
生成 JSON / Markdown 报告,上传 GitLab Artifact

这个流程最重要的设计点是:Vault 只保存已验证成功的密码。

如果主机不可达、账号不存在、远端密码修改失败、/etc/shadow 校验失败,或者 Vault 写入失败,都会在报告中记录状态,但不会把未确认的密码写入 Vault。

Vault 最小权限设计

Vault 中建议单独为自动化任务创建一个最小权限策略。这个任务只需要写入 dev 账号密码,不应该拥有 Vault 管理员权限。

策略示例:

cat > /tmp/ansible-dev-password-rotator.hcl <<'EOF'
path "secret/data/ansible/linux/accounts/dev/*" {
  capabilities = ["create", "update"]
}

path "secret/metadata/ansible/linux/accounts/dev/*" {
  capabilities = ["create", "update", "read", "list"]
}
EOF

vault policy write ansible-dev-password-rotator /tmp/ansible-dev-password-rotator.hcl

这里使用的是 Vault KV v2,因此真正写入数据的 API 路径是:

secret/data/ansible/linux/accounts/dev/<inventory_hostname>

而使用 Vault CLI 查看时路径是:

vault kv get secret/ansible/linux/accounts/dev/<inventory_hostname>

KV v2 的 API 路径和 CLI 路径不完全一样,这是很多人第一次接入 Vault 时容易踩坑的地方。

使用 AppRole 给 GitLab CI 授权

GitLab CI 不建议保存长期 Vault Token。更合适的方式是使用 Vault AppRole。

AppRole 的好处是:

  • GitLab 保存的是 role_id 和 secret_id。
  • 每次 CI job 开始时临时登录 Vault。
  • 登录成功后拿到短期 VAULT_TOKEN。
  • Ansible 后续使用这个短期 token 写入 Vault。

启用 AppRole:

vault auth enable approle

创建专用角色:

vault write auth/approle/role/ansible-dev-password-rotator \
  token_policies="ansible-dev-password-rotator" \
  token_ttl="1h" \
  token_max_ttl="2h" \
  secret_id_ttl="0" \
  secret_id_num_uses="0"

获取 role_id:

vault read auth/approle/role/ansible-dev-password-rotator/role-id

创建 secret_id:

vault write -f auth/approle/role/ansible-dev-password-rotator/secret-id

secret_id 只会显示一次,拿到后应立即保存到 GitLab CI/CD Variables,不要写入代码仓库。

Ansible 默认变量

Playbook 中通过环境变量读取 Vault 配置。这样本地运行和 CI 运行可以共用同一套逻辑。

# playbooks/04-security-baseline/vars/defaults.yml

dev_password_user: dev
dev_password_length: 12
dev_password_report_dir: reports/security-baseline/dev-password-rotation

dev_password_vault_addr: "{{ lookup('ansible.builtin.env', 'VAULT_ADDR') }}"
dev_password_vault_token: "{{ lookup('ansible.builtin.env', 'VAULT_TOKEN') }}"
dev_password_vault_namespace: "{{ lookup('ansible.builtin.env', 'VAULT_NAMESPACE') }}"

dev_password_vault_validate_certs: >-
  {{
    (lookup('ansible.builtin.env', 'VAULT_SKIP_VERIFY') | lower)
    not in ['1', 'true', 'yes']
  }}

dev_password_vault_ca_path: "{{ lookup('ansible.builtin.env', 'VAULT_CACERT') }}"

dev_password_vault_kv_mount: secret
dev_password_vault_path_prefix: ansible/linux/accounts/dev

dev_password_no_log: true

这里有几个关键点:

  • dev_password_no_log: true 用于避免 Ansible 输出明文密码、shadow hash 和 Vault token。
  • VAULT_SKIP_VERIFY=true 可临时关闭 Vault HTTPS 证书校验。
  • VAULT_CACERT 用于传入 Vault CA 证书路径,推荐在生产环境使用。
  • dev_password_vault_path_prefix 控制密码写入 Vault 的路径前缀。

Ansible 密码轮换核心逻辑

下面是单台主机的核心处理流程。

- name: Check dev account exists
  ansible.builtin.command: "getent passwd {{ dev_password_user }}"
  register: _dev_passwd
  changed_when: false
  failed_when: false

- name: Generate new dev password and hash on controller
  ansible.builtin.set_fact:
    _dev_password_plain: >-
      {{
        lookup(
          'ansible.builtin.password',
          '/dev/null length=' ~ dev_password_length ~ ' chars=ascii_letters,digits,punctuation'
        )
      }}
    _dev_password_rotated_at: "{{ lookup('pipe', 'TZ=Asia/Shanghai date -Iseconds') }}"
  no_log: "{{ dev_password_no_log }}"
  when: _dev_passwd.rc == 0

- name: Build stable dev password hash
  ansible.builtin.set_fact:
    _dev_password_hash: "{{ _dev_password_plain | password_hash('sha512') }}"
  no_log: "{{ dev_password_no_log }}"
  when: _dev_passwd.rc == 0

- name: Update dev password on remote host
  ansible.builtin.user:
    name: "{{ dev_password_user }}"
    password: "{{ _dev_password_hash }}"
    update_password: always
    password_lock: false
  register: _dev_user_update
  failed_when: false
  no_log: "{{ dev_password_no_log }}"
  when: _dev_passwd.rc == 0

这里没有直接把明文密码传给远端命令,而是在控制端生成 SHA-512 shadow hash,再通过 Ansible user 模块写入系统账号。

接着读取远端 /etc/shadow,确认写入后的 hash 和本次生成的 hash 是否一致。

- name: Read devshadow hash after password update
  ansible.builtin.command: "getent shadow {{ dev_password_user }}"
  register: _dev_shadow_after
  changed_when: false
  failed_when: false
  no_log: "{{ dev_password_no_log }}"
  when: _dev_passwd.rc == 0

- name: Decide whether remote password update is verified
  ansible.builtin.set_fact:
    _dev_password_verified: >-
      {{
        (_dev_passwd.rc == 0)
        and (_dev_user_update is defined)
        and not (_dev_user_update.failed | default(false))
        and ((_dev_shadow_after.rc | default(1)) == 0)
        and (((_dev_shadow_after.stdout | default('')).split(':')[1] | default('')) == _dev_password_hash)
      }}
  no_log: "{{ dev_password_no_log }}"
  when: _dev_passwd.rc == 0

只有 _dev_password_verified 为 true,才允许写 Vault。

- name: Write verified dev password to Vault KV v2
  ansible.builtin.uri:
    url: >-
      {{
        dev_password_vault_addr | regex_replace('/+$', '')
      }}/v1/{{ dev_password_vault_kv_mount }}/data/{{
        dev_password_vault_path_prefix | regex_replace('^/+', '') | regex_replace('/+$', '')
      }}/{{ inventory_hostname | urlencode }}
    method: POST
    headers: >-
      {{
        {'X-Vault-Token': dev_password_vault_token}
        | combine(
          (dev_password_vault_namespace | default('') | trim | length > 0)
          | ternary({'X-Vault-Namespace': dev_password_vault_namespace}, {})
        )
      }}
    body_format: json
    body:
      data:
        username: "{{ dev_password_user }}"
        password: "{{ _dev_password_plain }}"
        host: "{{ inventory_hostname }}"
        ansible_host: "{{ ansible_host | default('') }}"
        environment: "{{ custom_fields.environment | default('') }}"
        business_owner: "{{ custom_fields.business_owner | default('') }}"
        rotated_at: "{{ _dev_password_rotated_at }}"
        rotated_by: "ansible-deploy"
        verification: "shadow_hash_match"
    validate_certs: "{{ dev_password_vault_validate_certs }}"
    ca_path: >-
      {{
        dev_password_vault_ca_path
        if (dev_password_vault_ca_path | default('') | trim | length > 0)
        else omit
      }}
    status_code:
      - 200
      - 204
  register: _dev_vault_write
  changed_when: "_dev_vault_write.status | default(0) in [200, 204]"
  failed_when: false
  delegate_to: localhost
  become: false
  no_log: "{{ dev_password_no_log }}"
  when:
    - _dev_passwd.rc == 0
    - _dev_password_verified | default(false)

这段代码有两个细节很重要:

  • delegate_to: localhost:写 Vault 的动作在 Ansible 控制端执行,而不是在目标业务服务器上执行。
  • ca_path 和 validate_certs:让 Ansible 写 Vault 时也支持自定义 CA 证书。

GitLab CI 定时执行任务

GitLab CI 中定义 rotate_dev_password job,负责完成三件事:

  • 使用 AppRole 登录 Vault,换取短期 VAULT_TOKEN。
  • 执行 Ansible Playbook。
  • 检查报告结果,并上传 Artifact。

核心配置如下:

variables:
  ANSIBLE_INVENTORY: "inventories/netbox.yml"
  dev_PASSWORD_PLAYBOOK: "playbooks/04-security-baseline/rotate_dev_password.yml"
  dev_PASSWORD_ENV: ""
  dev_PASSWORD_LIMIT: ""
  dev_PASSWORD_EXTRA_VARS: ""
  dev_PASSWORD_ROTATE: "false"
  VAULT_APPROLE_AUTH_PATH: "approle"
  VAULT_SKIP_VERIFY: "false"
  ANSIBLE_CONFIG: "$CI_PROJECT_DIR/ansible.cfg"
  ANSIBLE_PRIVATE_KEY_FILE: "/root/.ssh/id_ed25519_ansible"
  ANSIBLE_HOST_KEY_CHECKING: "False"

rotate_dev_password job:

rotate_dev_password:
  stage: ops
  needs: []
  resource_group: dev-password-rotation
  timeout: 2h
  script:
    - |
      report_dir="reports/security-baseline/dev-password-rotation/gitlab-${CI_PIPELINE_ID}-${CI_JOB_ID}"
      ansible_limit=""
      mkdir -p ci_artifacts/dev-password-rotation

      if [ -n "${dev_PASSWORD_LIMIT:-}" ]; then
        ansible_limit="${dev_PASSWORD_LIMIT:-}"
      elif [ -n "${dev_PASSWORD_ENV:-}" ]; then
        ansible_limit="env_${dev_PASSWORD_ENV:-}"
      fi

      if [ -z "${VAULT_ADDR:-}" ]; then
        echo "ERROR: VAULT_ADDR is required"
        exit 1
      fi

      if [ -z "${VAULT_ROLE_ID:-}" ]; then
        echo "ERROR: VAULT_ROLE_ID is required"
        exit 1
      fi

      if [ -z "${VAULT_SECRET_ID:-}" ]; then
        echo "ERROR: VAULT_SECRET_ID is required"
        exit 1
      fi

      vault_headers=()
      if [ -n "${VAULT_NAMESPACE:-}" ]; then
        vault_headers+=(--header "X-Vault-Namespace: ${VAULT_NAMESPACE}")
      fi

      vault_curl_args=()
      if [ "${VAULT_SKIP_VERIFY:-false}" = "true" ]; then
        vault_curl_args+=(--insecure)
      elif [ -n "${VAULT_CACERT:-}" ]; then
        vault_curl_args+=(--cacert "$VAULT_CACERT")
      fi

      login_payload="$(python3 - <<'PY'
      import json
      import os

      print(json.dumps({
          "role_id": os.environ["VAULT_ROLE_ID"],
          "secret_id": os.environ["VAULT_SECRET_ID"],
      }))
      PY
      )"

      login_resp="$(curl -sS --request POST \
        "${vault_curl_args[@]}" \
        "${vault_headers[@]}" \
        --data "$login_payload" \
        "${VAULT_ADDR%/}/v1/auth/${VAULT_APPROLE_AUTH_PATH:-approle}/login")"

      export VAULT_TOKEN="$(python3 -c '
      import json
      import sys

      resp = json.load(sys.stdin)
      errors = resp.get("errors")
      if errors:
          raise SystemExit("Vault AppRole login failed: " + "; ".join(map(str, errors)))
      token = resp.get("auth", {}).get("client_token")
      if not token:
          raise SystemExit("Vault AppRole login response did not contain auth.client_token")
      print(token)
      ' <<< "$login_resp")"

      cmd=(
        ansible-playbook
        -i "$ANSIBLE_INVENTORY"
        "$dev_PASSWORD_PLAYBOOK"
        -e "dev_password_report_dir=${report_dir}"
      )

      if [ -n "$ansible_limit" ]; then
        cmd+=(--limit "$ansible_limit")
      fi

      if [ -n "$dev_PASSWORD_EXTRA_VARS" ]; then
        cmd+=(--extra-vars "$dev_PASSWORD_EXTRA_VARS")
      fi

      echo "Running: ansible-playbook -i ${ANSIBLE_INVENTORY} ${dev_PASSWORD_PLAYBOOK}"
      set +e
      "${cmd[@]}"
      playbook_rc=$?
      set -e

      if [ ! -d "$report_dir" ] || [ -z "$(ls -A "$report_dir" 2>/dev/null)" ]; then
        echo "Report directory was not generated: $report_dir (ansible-playbook rc=${playbook_rc})"
        exit "${playbook_rc:-1}"
      fi

      mkdir -p ci_artifacts/dev-password-rotation
      cp -a "${report_dir}/." ci_artifacts/dev-password-rotation/

      latest_json=""
      for report_json in "$report_dir"/dev_password_rotation_*.json; do
        latest_json="$report_json"
      done

      if [ -z "$latest_json" ]; then
        echo "No JSON report found under $report_dir"
        exit 1
      fi

      python3 - "$latest_json" <<'PY'
      import json
      import sys

      report_path = sys.argv[1]
      with open(report_path, "r", encoding="utf-8") as fh:
          report = json.load(fh)

      summary = report.get("summary", {})
      total = int(summary.get("total", 0))
      success = int(summary.get("success", 0))
      failed = total - success

      print(f"Password rotation summary: success={success} failed={failed} total={total}")
      if failed:
          sys.exit(1)
      PY

      if [ "$playbook_rc" -ne 0 ]; then
        exit "$playbook_rc"
      fi
  artifacts:
    name: "dev-password-rotation-${CI_PIPELINE_ID}-${CI_JOB_ID}"
    when: always
    expire_in: 30 days
    paths:
      - ci_artifacts/dev-password-rotation/
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule" && $dev_PASSWORD_ROTATE == "true"'
      when: on_success
      allow_failure: false
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: manual
      allow_failure: false
    - when: manual
      allow_failure: false

这里使用 resource_group: dev-password-rotation 是为了避免多个密码轮换任务并发执行。密码轮换属于高风险操作,宁愿排队,也不要同时跑多个 job。

GitLab CI/CD Variables 配置

项目中需要配置以下变量:

变量类型建议说明
VAULT_ADDR普通变量Vault 地址,例如 https://vault.example.com:8200
VAULT_ROLE_IDProtectedAppRole 的 role_id
VAULT_SECRET_IDMasked + ProtectedAppRole 的 secret_id
VAULT_APPROLE_AUTH_PATH普通变量,可选默认是 approle
VAULT_NAMESPACE普通变量,可选Vault Enterprise namespace
VAULT_CACERTFile 类型Vault HTTPS CA 证书
VAULT_SKIP_VERIFY普通变量临时跳过证书校验,生产不建议
dev_PASSWORD_ROTATESchedule 变量设置为 true 才允许定时轮换
dev_PASSWORD_ENV可选例如 dmztest,转换成 --limit env_dmztest
dev_PASSWORD_LIMIT可选直接传 Ansible limit,优先级更高

定时任务建议在 GitLab CI/CD -> Schedules 中配置,并在 Schedule 变量里设置:

dev_PASSWORD_ROTATE=true

如果只轮换某个环境:

dev_PASSWORD_ENV=dmztest

报告设计:不要输出明文密码

密码轮换完成后,会生成 JSON 和 Markdown 两份报告。

报告只记录:

  • 主机名
  • IP
  • 环境
  • 系统信息
  • Vault 路径
  • 轮换时间
  • 执行状态
  • 错误原因

不会记录:

  • 明文密码
  • shadow hash
  • Vault token

Markdown 报告模板示例:

# dev 密码轮换报告

- **生成时间**:{{ report_generated_at }}
- **目标范围**:{{ dev_password_summary.total }} 台(`protocol_ssh`)
- **Vault KV v2 路径前缀**:`{{ dev_password_summary.vault_mount }}/data/{{ dev_password_summary.vault_path_prefix }}`
- **说明**:报告不包含明文密码;成功主机的密码已写入 Vault。

## 汇总

| 状态 | 数量 |
|------|------|
| 成功,已写入 Vault (success) | {{ dev_password_summary.success }} |
| dev 账号不存在 (account_missing) | {{ dev_password_summary.account_missing }} |
| 远端修改失败 (change_failed) | {{ dev_password_summary.change_failed }} |
| 远端确认失败,未写 Vault (verify_failed) | {{ dev_password_summary.verify_failed }} |
| Vault 写入失败 (vault_failed) | {{ dev_password_summary.vault_failed }} |
| 不可达 (unreachable) | {{ dev_password_summary.unreachable }} |
| **合计** | **{{ dev_password_summary.total }}** |

这种报告适合直接作为 GitLab Artifact 保存,方便后续审计和问题追踪。

报告示例:

踩坑一:curl SSL certificate problem

实际运行时遇到过这个错误:

curl: (60) SSL certificate problem: unable to get local issuer certificate

这个错误发生在 GitLab CI 执行 AppRole 登录时:

curl -sS --request POST \
  --data "$login_payload" \
  "${VAULT_ADDR%/}/v1/auth/${VAULT_APPROLE_AUTH_PATH:-approle}/login"

它的意思是:GitLab Runner 不信任 Vault HTTPS 证书链。

Vault 服务器上通常会有类似文件:

/data/vault/tls/ca.crt
/data/vault/tls/vault.crt
/data/vault/tls/vault.key
/data/vault/pki/vault-ca.crt
/data/vault/pki/vault-ca.key

这些文件的作用不同:

文件作用是否可以放进 GitLab
ca.crt 或 vault-ca.crtCA 证书,用于客户端信任 Vault可以
vault.crtVault 服务端证书不推荐作为 VAULT_CACERT
vault.keyVault 服务端私钥绝对不可以
vault-ca.keyCA 私钥绝对不可以

正确做法是在 GitLab 项目 Settings -> CI/CD -> Variables 添加:

Key: VAULT_CACERT
Type: File
Value: 粘贴 /data/vault/tls/ca.crt 的完整内容

证书内容类似:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

GitLab 的 File 类型变量有一个特点:它不会把变量值直接作为字符串注入,而是在 job 运行时生成一个临时文件,然后让 VAULT_CACERT 指向这个文件路径。

所以脚本中可以这样使用:

curl --cacert "$VAULT_CACERT" ...

VAULT_CACERT 解决的是“Runner 如何信任 Vault HTTPS 证书”的问题。它不是 Vault 权限凭据,也不会泄露 Vault 私钥。

踩坑二:临时跳过证书校验可以,但不要长期使用

脚本中支持:

VAULT_SKIP_VERIFY=true

开启后,CI 登录 Vault 时会使用:

curl --insecure ...

Ansible 写 Vault 阶段也会关闭证书校验。

这个方式适合临时排查问题,但不建议长期使用。因为它绕过了 HTTPS 证书校验,无法确认当前连接的 Vault 服务是否真的是预期目标。

生产环境推荐使用 VAULT_CACERT。

踩坑三:不要把密码写入 Vault 后才校验

一个容易犯的错误是:

生成密码 -> 写 Vault -> 改远端密码

或者:

生成密码 -> 改远端密码 -> 不校验直接写 Vault

这两种方式都有风险。

如果远端密码修改失败,但 Vault 已经保存了新密码,就会出现 Vault 中的密码和服务器真实密码不一致的问题。后续运维人员按 Vault 密码登录,会发现根本无法使用。

更稳妥的顺序应该是:

生成密码 -> 修改远端 -> 读取 /etc/shadow 校验 -> 成功后写 Vault

这也是本方案最核心的安全逻辑。

踩坑四:GitLab Artifact 上传成功不代表任务成功

这次排错时还有一个容易误判的点:job 失败后仍然上传了 artifact。

日志中可以看到:

Uploading artifacts...
ci_artifacts/dev-password-rotation/: found 1 matching artifact files and directories
Uploading artifacts as "archive" to coordinator... 201 Created

这并不表示密码轮换成功。

原因是 CI 脚本开头创建了 artifact 目录:

mkdir -p ci_artifacts/dev-password-rotation

即使后续 Vault 登录失败,GitLab 也能上传这个空目录或已有目录。

判断任务是否成功,要看:

  • job 最终 exit code
  • Password rotation summary
  • JSON 报告中的 summary
  • Markdown 报告中的失败主机列表

总结

通过 Ansible + HashiCorp Vault + GitLab CI,可以把 Linux 账号密码轮换从手工操作升级为可审计、可定时、可回滚排查的自动化流程。

这套方案的关键优势是:

  • GitLab CI 负责任务编排和定时触发。
  • Vault AppRole 提供短期 token,避免长期 token 泄露风险。
  • Ansible 逐台修改密码,并用 /etc/shadow 做结果确认。
  • 只有确认成功的主机才写入 Vault,避免密码托管数据失真。
  • 报告不包含明文密码,但保留足够的审计信息。
  • VAULT_CACERT 解决内网 Vault 自签名证书的可信问题。

最终落地时,最重要的不是“能不能批量改密码”,而是这条原则:

密码轮换任务必须以远端真实状态为准。只有服务器确认修改成功,Vault 才能保存新密码。