.pre-commit-config.yaml

@@ -22,3 +22,12 @@ repos:
             "-d {extends: relaxed, rules: {line-length: disable}, ignore: chart}",
             "-s",
           ]
+  - repo: local
+    hooks:
+      - id: vault-yaml-tests
+        name: vault yaml definitions pass their unit tests
+        entry: python3 -m unittest discover -s tests -t .
+        language: python
+        additional_dependencies: [pyyaml, pydantic]
+        pass_filenames: false
+        always_run: true

Makefile

@@ -1,4 +1,4 @@
-.PHONY: init plan apply format
+.PHONY: init plan apply format test
 
 VAULT_AUTH_METHOD ?= approle
 VAULT_K8S_ROLE ?= woodpecker_terraform_vault
@@ -28,6 +28,9 @@ apply: init
 	@$(call vault_env) && \
 	terragrunt run --all --parallelism 2 --non-interactive apply
 
+test:
+	@uv run --with pyyaml --with pydantic python -m unittest discover -s tests -t .
+
 format:
 	@echo "Formatting OpenTofu files..."
 	@tofu fmt -recursive .

policies/gpg/admin.yaml

@@ -1,20 +1,8 @@
-# Allow the vault deployer to import the gpg plugin and manage its OpenPGP keys.
-#
-# terraform-vault registers the plugin itself (vault_plugin -> sys/plugins/catalog,
-# a sudo-protected path) and manages keys via the gpgvaultsecret provider, so the
-# deployer needs catalog access on top of the mount access it already has
-# (sys/mounts/*). Without this, apply 403s on the plugin registration and on
-# gpg/keys writes.
+# Allow the vault deployer to manage the gpg mount's OpenPGP keys via the
+# gpgvaultsecret provider. Registering the plugin itself is a sys/plugins/catalog
+# grant, carried by policies/sys/plugins/catalog/admin.yaml.
 ---
 rules:
-  # Import / register (and deregister) the gpg plugin in the catalog.
-  - path: "sys/plugins/catalog/secret/vault-plugin-secrets-gpg"
-    capabilities:
-      - create
-      - read
-      - update
-      - delete
-      - sudo
   # Manage keys (create/rotate/config/delete) in the gpg mount.
   - path: "gpg/keys/*"
     capabilities:

policies/identity/group-alias/admin.yaml

@@ -0,0 +1,24 @@
+# Allow the deployer to manage the identity group aliases that map external OIDC
+# group membership (the ak_groups claim) onto the Vault groups managed under
+# policies/identity/group/. Both endpoints are needed: create posts to
+# identity/group-alias, subsequent reads and updates address
+# identity/group-alias/id/<id>.
+---
+rules:
+  - path: "identity/group-alias"
+    capabilities:
+      - create
+      - update
+  - path: "identity/group-alias/*"
+    capabilities:
+      - create
+      - update
+      - read
+      - delete
+      - list
+
+auth:
+  approle:
+    - tf_vault
+  k8s/au/syd1:
+    - woodpecker_terraform_vault

policies/identity/group/admin.yaml

@@ -1,7 +1,7 @@
-# Allow the deployer to manage external identity groups and their aliases, which
-# is how OIDC group membership (the ak_groups claim) maps onto Vault policies.
-# Both the collection endpoints and the per-id endpoints are needed: create posts
-# to identity/group, subsequent reads and updates address identity/group/id/<id>.
+# Allow the deployer to manage the external identity groups that OIDC group
+# membership (the ak_groups claim) maps onto Vault policies through. Both the
+# collection endpoint and the per-id endpoints are needed: create posts to
+# identity/group, subsequent reads and updates address identity/group/id/<id>.
 ---
 rules:
   - path: "identity/group"
@@ -15,21 +15,6 @@ rules:
       - read
       - delete
       - list
-  - path: "identity/group-alias"
-    capabilities:
-      - create
-      - update
-  - path: "identity/group-alias/*"
-    capabilities:
-      - create
-      - update
-      - read
-      - delete
-      - list
-  - path: "identity/lookup/group"
-    capabilities:
-      - create
-      - update
 
 auth:
   approle:

policies/identity/lookup/group/admin.yaml

@@ -0,0 +1,14 @@
+# Allow the deployer to look up an identity group by name, which is how it
+# resolves the group it is about to update under policies/identity/group/.
+---
+rules:
+  - path: "identity/lookup/group"
+    capabilities:
+      - create
+      - update
+
+auth:
+  approle:
+    - tf_vault
+  k8s/au/syd1:
+    - woodpecker_terraform_vault

policies/kv/kubernetes/namespace/+/default/oauth-credentials/read.yaml

@@ -0,0 +1,15 @@
+# Allow the Terraform Authentik runner to read the OAuth2/OIDC client secret that
+# backs an authentik provider, in whichever namespace the target service lives
+# (the module's data.vault_kv_secret_v2). The literal + is a Vault single-segment
+# wildcard: one oauth-credentials secret per onboarded namespace.
+---
+rules:
+  - path: "kv/data/kubernetes/namespace/+/default/oauth-credentials"
+    capabilities:
+      - read
+
+auth:
+  approle:
+    - terraform_authentik
+  k8s/au/syd1:
+    - woodpecker_terraform_authentik

policies/kv/kubernetes/namespace/cattle-system/default/oauth-credentials/read.yaml

@@ -0,0 +1,14 @@
+# Allow the Terraform Rancher runner to read the OAuth2/OIDC client secret backing
+# the Rancher keycloakoidc AuthConfig (the same secret Authentik sets on the
+# provider).
+---
+rules:
+  - path: "kv/data/kubernetes/namespace/cattle-system/default/oauth-credentials"
+    capabilities:
+      - read
+
+auth:
+  approle:
+    - terraform_rancher
+  k8s/au/syd1:
+    - woodpecker_terraform_rancher

policies/kv/kubernetes/namespace/logging/default/vlogs-oauth-credentials/read.yaml

@@ -0,0 +1,14 @@
+# Allow the Terraform Authentik runner to read the vlogs OIDC client secret. It is
+# a second OIDC client in an already-onboarded namespace, so it cannot use the
+# one-per-namespace oauth-credentials path.
+---
+rules:
+  - path: "kv/data/kubernetes/namespace/logging/default/vlogs-oauth-credentials"
+    capabilities:
+      - read
+
+auth:
+  approle:
+    - terraform_authentik
+  k8s/au/syd1:
+    - woodpecker_terraform_authentik

policies/kv/service/terraform/authentik.yaml

@@ -1,20 +1,11 @@
-# Allow the Terraform Authentik runner to read:
-#  - its own Authentik API token (provider auth), and
-#  - OAuth2/OIDC client secrets that back authentik providers (per target
-#    service's kv namespace path, via the module's data.vault_kv_secret_v2).
+# Allow the Terraform Authentik runner to read its own Authentik API token
+# (provider auth). The OAuth2/OIDC client secrets backing authentik providers are
+# granted per secret under policies/kv/kubernetes/namespace/.
 ---
 rules:
   - path: "kv/data/service/terraform/authentik"
     capabilities:
       - read
-  - path: "kv/data/kubernetes/namespace/+/default/oauth-credentials"
-    capabilities:
-      - read
-  # Second OIDC client in an already-onboarded namespace, so it cannot use the
-  # one-per-namespace oauth-credentials path above.
-  - path: "kv/data/kubernetes/namespace/logging/default/vlogs-oauth-credentials"
-    capabilities:
-      - read
 
 auth:
   approle:

policies/kv/service/terraform/rancher.yaml

@@ -1,15 +1,11 @@
-# Allow the Terraform Rancher runner to read:
-#  - its own Rancher admin API token (rancher2 provider auth), and
-#  - the OAuth2/OIDC client secret backing the Rancher keycloakoidc AuthConfig
-#    (same secret Authentik sets on the provider).
+# Allow the Terraform Rancher runner to read its own Rancher admin API token
+# (rancher2 provider auth). The OAuth2/OIDC client secret backing the Rancher
+# keycloakoidc AuthConfig is granted under policies/kv/kubernetes/namespace/.
 ---
 rules:
   - path: "kv/data/service/terraform/rancher"
     capabilities:
       - read
-  - path: "kv/data/kubernetes/namespace/cattle-system/default/oauth-credentials"
-    capabilities:
-      - read
 
 auth:
   approle:

policies/sys/mounts-tune/admin.yaml

@@ -0,0 +1,15 @@
+# Allow the deployer to read and tune the configuration of a mounted secret
+# engine. sys/mounts-tune is the tuning endpoint beside the mount management
+# granted by policies/sys/mounts/admin.yaml.
+---
+rules:
+  - path: "sys/mounts-tune/*"
+    capabilities:
+      - update
+      - read
+
+auth:
+  approle:
+    - tf_vault
+  k8s/au/syd1:
+    - woodpecker_terraform_vault

policies/sys/mounts/admin.yaml

@@ -8,10 +8,6 @@ rules:
       - delete
       - read
       - list
-  - path: "sys/mounts-tune/*"
-    capabilities:
-      - update
-      - read
   - path: "sys/mounts"
     capabilities:
       - read

tests/test_policies.py

@@ -0,0 +1,106 @@
+"""Validate the Vault policy definitions under policies/."""
+import unittest
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+# kv-v2 inserts one of these directly after the mount; it is not part of the scope.
+KV_API_SEGMENTS = {"data", "metadata", "delete", "undelete", "destroy"}
+
+
+class Rule(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str = Field(min_length=1)
+    capabilities: list[
+        Literal["create", "read", "update", "patch", "delete", "list", "sudo", "deny"]
+    ] = Field(min_length=1)
+
+
+class Policy(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    rules: list[Rule] = Field(min_length=1)
+    auth: dict[str, list[str]]
+
+
+def policy_files():
+    return sorted(REPO_ROOT.glob("policies/**/*.yaml"))
+
+
+def escaping_scope(policy_file, rule_path):
+    """The policy directory a rule path reaches outside of, or None when in scope."""
+    parts = PurePosixPath(policy_file).parts
+    # a policy at the policies/ root is located at the root, so its scope is the whole tree
+    scope = PurePosixPath(*parts[parts.index("policies") + 1:]).parent
+    path = PurePosixPath(rule_path)
+    if len(path.parts) > 1 and path.parts[1] in KV_API_SEGMENTS:
+        path = PurePosixPath(path.parts[0], *path.parts[2:])
+    return None if path.is_relative_to(scope) else str(scope)
+
+
+class PolicyFileTests(unittest.TestCase):
+    def setUp(self):
+        self.files = policy_files()
+        self.assertTrue(self.files, f"no policy files discovered under {REPO_ROOT}/policies")
+
+    def test_schema(self):
+        for f in self.files:
+            with self.subTest(path=f.relative_to(REPO_ROOT).as_posix()):
+                Policy.model_validate(yaml.safe_load(f.read_text()))
+
+    def test_paths(self):
+        for f in self.files:
+            rel = f.relative_to(REPO_ROOT).as_posix()
+            for rule in yaml.safe_load(f.read_text()).get("rules") or []:
+                rule_path = rule.get("path")
+                with self.subTest(path=rel, rule=rule_path):
+                    self.assertIsNotNone(rule_path, "rule has no path")
+                    scope = escaping_scope(rel, rule_path)
+                    self.assertIsNone(scope, f'rule path "{rule_path}" escapes policy scope "{scope}"')
+
+
+class RuleScopeTests(unittest.TestCase):
+    """The scope rule against fixtures, so a clean tree cannot hide a broken check."""
+
+    def test_in_scope(self):
+        for policy_file, rule_path in [
+            ("policies/sys/mounts/admin.yaml", "sys/mounts"),
+            ("policies/sys/mounts/admin.yaml", "sys/mounts/*"),
+            ("policies/rundeck/rundeck.yaml", "rundeck/data/*"),
+            ("policies/rundeck/rundeck.yaml", "rundeck/metadata/*"),
+            ("policies/kv/service/authentik/oidc-vault/read.yaml", "kv/data/service/authentik/oidc-vault"),
+            ("policies/kv/service/vault/read.yaml", "kv/data/service/vault/+/+/auth_backend/*"),
+            ("policies/kubernetes/au/admin.yaml", "kubernetes/au/+/config"),
+            ("policies/global-root.yaml", "*"),  # a root-level policy is scoped to the whole tree
+        ]:
+            with self.subTest(policy=policy_file, rule=rule_path):
+                self.assertIsNone(escaping_scope(policy_file, rule_path))
+
+    def test_escapes(self):
+        for policy_file, rule_path, scope in [
+            ("policies/sys/thing/admin.yaml", "sys/thing-tune/*", "sys/thing"),
+            ("policies/kv/foo/bar/baz.yaml", "kv/data/foo/baz/bar", "kv/foo/bar"),
+            ("policies/kv/service/vault/au/syd1/ghp/w.yaml", "kv/data/service/vault/+/+/ghp/config", "kv/service/vault/au/syd1/ghp"),
+        ]:
+            with self.subTest(policy=policy_file, rule=rule_path):
+                self.assertEqual(escaping_scope(policy_file, rule_path), scope)
+
+    def test_schema_rejects_malformed(self):
+        auth = {"approle": ["tf_vault"]}
+        rule = {"path": "kv/data/x", "capabilities": ["read"]}
+        for doc in [
+            {"auth": auth},  # no rules
+            {"rules": [], "auth": auth},  # empty rules
+            {"rules": [{"capabilities": ["read"]}], "auth": auth},  # rule without a path
+            {"rules": [{"path": "kv/data/x", "capabilities": []}], "auth": auth},  # rule without capabilities
+            {"rules": [{"path": "kv/data/x", "capabilities": ["write"]}], "auth": auth},  # not a Vault capability
+            {"rules": [rule]},  # no auth
+            {"rules": [rule], "auth": auth, "rulez": []},  # typo'd top-level key
+        ]:
+            with self.subTest(doc=doc), self.assertRaises(ValidationError):
+                Policy.model_validate(doc)