feat: honor ANSIBLE_VAULT_PASSWORD_FILE for vault decryption

Delegate vault secret initialization to Ansible's own
CLI.setup_vault_secrets(), which reads:

- ANSIBLE_VAULT_PASSWORD_FILE environment variable
- vault_password_file in ansible.cfg
- ANSIBLE_VAULT_IDENTITY_LIST / vault_identity_list

Previously, all DataLoader instances were initialized with a hardcoded
dummy vault password "x", causing decryption failures for fully
encrypted vault files (e.g., group_vars/*/vault.yaml). This meant
JinjaRule and VariableNamingRule silently skipped vault files.

The fix centralizes vault secret loading in _get_vault_secrets() which
caches the result and falls back to the dummy password when no vault
configuration is found. All three DataLoader creation sites
(parse_yaml_from_file, path_dwim, ansible_templar) now use the shared
_make_dataloader() factory.

Interactive prompts are disabled (ask_vault_pass=False, auto_prompt=False).

Fixes #2889, #2506, #2443, #3718
Supersedes #4069

Signed-off-by: John Lahr <john@johnlahr.me>

Author: JohnLahr

docs/usage.md

@@ -287,10 +287,17 @@ follows:
 
 ## Vaults
 
-As ansible-lint executes ansible, it also needs access to encrypted secrets. If
-you do not give access to them or you are concerned about security implications,
-you should consider refactoring your code to allow it to be linted without
-access to real secrets:
+Ansible-lint honors the same vault configuration sources that `ansible-playbook`
+uses, so it can decrypt vault-encrypted files during linting:
+
+- `ANSIBLE_VAULT_PASSWORD_FILE` environment variable
+- `vault_password_file` in `ansible.cfg`
+- `ANSIBLE_VAULT_IDENTITY_LIST` / `vault_identity_list`
+
+Interactive prompts (`--ask-vault-pass`) are not supported.
+
+If you do not give access to vault secrets or you are concerned about security
+implications, you can lint without access to real secrets:
 
 - Configure dummy fallback values that are used during linting, so Ansible will
   not complain about undefined variables.

examples/playbooks/vars/vault_encrypted.yml

@@ -0,0 +1,6 @@
+$ANSIBLE_VAULT;1.1;AES256
+66386639366132393765316562616337613062313164336432346166346534386264306262373838
+6661313433613237653261323861323231393662343666350a366439633762613134666432623732
+38656632346532333339303365323863373939663036613038363339653730653136326161303134
+3464353961303161380a306463393935646234643663373065633936303635663530376130363130
+61323530386466643865333530353231333838323564653333643736353636363633

src/ansiblelint/utils.py

@@ -55,6 +55,8 @@
         to_bytes,
     )
 
+from ansible import constants as C
+from ansible.cli import CLI
 from ansible.module_utils.parsing.convert_bool import boolean
 from ansible.parsing.dataloader import DataLoader
 from ansible.parsing.mod_args import ModuleArgsParser
@@ -106,9 +108,7 @@
 if TYPE_CHECKING:
     from ansiblelint.app import App
     from ansiblelint.rules import RulesCollection
-# ansible-lint doesn't need/want to know about encrypted secrets, so we pass a
-# string as the password to enable such yaml files to be opened and parsed
-# successfully.
+# Fallback vault password used when no vault configuration is found.
 DEFAULT_VAULT_PASSWORD = "x"  # noqa: S105
 
 PLAYBOOK_DIR = os.environ.get("ANSIBLE_PLAYBOOK_DIR", None)
@@ -119,14 +119,63 @@
 
 _logger = logging.getLogger(__name__)
 
+# Cached vault secrets, initialized on first use.
+_vault_secrets: list[tuple[str, Any]] | None = None
+
+
+def _get_vault_secrets() -> list[tuple[str, Any]]:
+    """Return vault secrets from Ansible configuration, falling back to a dummy password."""
+    # pylint: disable=global-statement
+    global _vault_secrets
+    if _vault_secrets is not None:
+        return _vault_secrets
+
+    loader = DataLoader()  # type: ignore[no-untyped-call,unused-ignore]
+
+    vault_ids = (
+        list(C.DEFAULT_VAULT_IDENTITY_LIST)
+        if C.DEFAULT_VAULT_IDENTITY_LIST
+        else []
+    )
+
+    try:
+        secrets = CLI.setup_vault_secrets(
+            loader,
+            vault_ids=vault_ids,
+            ask_vault_pass=False,
+            auto_prompt=False,
+            initialize_context=False,
+        )
+        if secrets:
+            _vault_secrets = secrets
+            return _vault_secrets
+    except (AnsibleError, RuntimeError):
+        _logger.debug(
+            "Failed to load vault secrets from configuration",
+            exc_info=True,
+        )
+
+    # Fall back to dummy password for backward compatibility
+    _vault_secrets = [
+        (
+            "default",
+            PromptVaultSecret(_bytes=to_bytes(DEFAULT_VAULT_PASSWORD)),  # type: ignore[no-untyped-call]
+        ),
+    ]
+    return _vault_secrets
+
+
+def _make_dataloader() -> DataLoader:
+    """Create a DataLoader with vault secrets from Ansible configuration."""
+    loader = DataLoader()  # type: ignore[no-untyped-call,unused-ignore]
+    if hasattr(loader, "set_vault_secrets"):
+        loader.set_vault_secrets(_get_vault_secrets())
+    return loader
+
 
 def parse_yaml_from_file(filepath: str) -> AnsibleJSON:
     """Extract a decrypted YAML object from file."""
-    dataloader = DataLoader()  # type: ignore[no-untyped-call,unused-ignore]
-    if hasattr(dataloader, "set_vault_secrets"):
-        dataloader.set_vault_secrets([
-            ("default", PromptVaultSecret(_bytes=to_bytes(DEFAULT_VAULT_PASSWORD)))  # type: ignore[no-untyped-call]
-        ])
+    dataloader = _make_dataloader()
     result: object = dataloader.load_from_file(filepath)
     if result is None:
         return result
@@ -139,7 +188,7 @@ def parse_yaml_from_file(filepath: str) -> AnsibleJSON:
 
 def path_dwim(basedir: str, given: str) -> str:
     """Convert a given path do-what-I-mean style."""
-    dataloader = DataLoader()  # type: ignore[no-untyped-call,unused-ignore]
+    dataloader = _make_dataloader()
     dataloader.set_basedir(basedir)
     return str(dataloader.path_dwim(given))
 
@@ -154,7 +203,7 @@ def ansible_templar(basedir: Path, templatevars: Any) -> Templar:
     if basedir.name == "tasks":
         basedir = basedir.parent
 
-    dataloader = DataLoader()  # type: ignore[no-untyped-call,unused-ignore]
+    dataloader = _make_dataloader()
     dataloader.set_basedir(str(basedir))
     templar = Templar(dataloader, variables=templatevars)
     return templar

test/test_vault.py

@@ -0,0 +1,67 @@
+"""Tests for vault secret initialization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from ansible import constants as C
+from ansible.errors import AnsibleError
+
+from ansiblelint import utils
+
+
+VAULT_PASS_FILE = str(Path(__file__).parent.parent / ".vault_pass")
+VAULT_ENCRYPTED_FILE = str(
+    Path(__file__).parent.parent / "examples/playbooks/vars/vault_encrypted.yml"
+)
+
+
+@pytest.fixture(autouse=True)
+def _reset_vault_cache() -> None:
+    """Reset the cached vault secrets between tests."""
+    utils._vault_secrets = None  # noqa: SLF001
+
+
+def test_vault_secrets_loaded() -> None:
+    """Vault secrets are loaded from ansible configuration."""
+    secrets = utils._get_vault_secrets()  # noqa: SLF001
+    assert len(secrets) >= 1
+    _vault_id, secret = secrets[0]
+    # Should be the real password from .vault_pass, not the dummy
+    assert secret.bytes != b"x"
+
+
+def test_vault_secrets_fallback() -> None:
+    """Dummy password is returned when no vault configuration exists."""
+    with patch.object(C, "DEFAULT_VAULT_PASSWORD_FILE", None):
+        secrets = utils._get_vault_secrets()  # noqa: SLF001
+        assert len(secrets) == 1
+        _vault_id, secret = secrets[0]
+        assert secret.bytes == b"x"
+
+
+def test_vault_secrets_bad_file() -> None:
+    """Graceful fallback when vault password file does not exist."""
+    with patch.object(C, "DEFAULT_VAULT_PASSWORD_FILE", "/nonexistent/vault_pass"):
+        secrets = utils._get_vault_secrets()  # noqa: SLF001
+        assert len(secrets) == 1
+        _vault_id, secret = secrets[0]
+        assert secret.bytes == b"x"
+
+
+def test_vault_decrypt_with_password() -> None:
+    """Vault-encrypted files are decrypted when password is available."""
+    result = utils.parse_yaml_from_file(VAULT_ENCRYPTED_FILE)
+    assert result is not None
+    assert isinstance(result, dict)
+    assert result["my_secret"] == "test_value"
+
+
+def test_vault_decrypt_without_password() -> None:
+    """Vault-encrypted files cannot be decrypted with the dummy password."""
+    with patch.object(C, "DEFAULT_VAULT_PASSWORD_FILE", None):
+        with pytest.raises(AnsibleError, match="Decryption failed"):
+            utils.parse_yaml_from_file(VAULT_ENCRYPTED_FILE)