vault-approle-toolkit 0.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. vault_approle/VERSION +1 -0
  2. vault_approle/__init__.py +72 -0
  3. vault_approle/auth/__init__.py +9 -0
  4. vault_approle/auth/approle.py +68 -0
  5. vault_approle/auth/base.py +53 -0
  6. vault_approle/auth/token_passthrough.py +70 -0
  7. vault_approle/bootstrap/__init__.py +19 -0
  8. vault_approle/bootstrap/base.py +58 -0
  9. vault_approle/bootstrap/env.py +108 -0
  10. vault_approle/bootstrap/file.py +103 -0
  11. vault_approle/bootstrap/wrapped.py +101 -0
  12. vault_approle/cli/__init__.py +5 -0
  13. vault_approle/cli/approle.py +313 -0
  14. vault_approle/cli/aws.py +58 -0
  15. vault_approle/cli/common.py +130 -0
  16. vault_approle/cli/config_cmd.py +130 -0
  17. vault_approle/cli/doctor.py +53 -0
  18. vault_approle/cli/ecr.py +108 -0
  19. vault_approle/cli/main.py +92 -0
  20. vault_approle/cli/run.py +95 -0
  21. vault_approle/cli/session_cmd.py +127 -0
  22. vault_approle/cli/version_cmd.py +102 -0
  23. vault_approle/config.py +267 -0
  24. vault_approle/delivery/__init__.py +24 -0
  25. vault_approle/delivery/docker_config.py +234 -0
  26. vault_approle/delivery/dotenv.py +28 -0
  27. vault_approle/delivery/json_out.py +22 -0
  28. vault_approle/delivery/shell_export.py +55 -0
  29. vault_approle/delivery/subprocess_env.py +96 -0
  30. vault_approle/errors.py +115 -0
  31. vault_approle/http.py +215 -0
  32. vault_approle/logging.py +128 -0
  33. vault_approle/policy.py +356 -0
  34. vault_approle/profiles/builtin.json +32 -0
  35. vault_approle/providers/__init__.py +37 -0
  36. vault_approle/providers/aws/__init__.py +6 -0
  37. vault_approle/providers/aws/ecr.py +125 -0
  38. vault_approle/providers/aws/helpers.py +106 -0
  39. vault_approle/providers/aws/sts.py +103 -0
  40. vault_approle/providers/base.py +140 -0
  41. vault_approle/providers/registry.py +80 -0
  42. vault_approle/redact.py +112 -0
  43. vault_approle/session.py +325 -0
  44. vault_approle/table.py +28 -0
  45. vault_approle/token.py +198 -0
  46. vault_approle/vault/__init__.py +5 -0
  47. vault_approle/vault/client.py +200 -0
  48. vault_approle/versions.py +295 -0
  49. vault_approle_toolkit-0.2.1.dist-info/METADATA +247 -0
  50. vault_approle_toolkit-0.2.1.dist-info/RECORD +54 -0
  51. vault_approle_toolkit-0.2.1.dist-info/WHEEL +5 -0
  52. vault_approle_toolkit-0.2.1.dist-info/entry_points.txt +2 -0
  53. vault_approle_toolkit-0.2.1.dist-info/licenses/LICENSE +201 -0
  54. vault_approle_toolkit-0.2.1.dist-info/top_level.txt +1 -0
vault_approle/VERSION ADDED
@@ -0,0 +1 @@
1
+ 0.2.1
@@ -0,0 +1,72 @@
1
+ """Vault AppRole Toolkit.
2
+
3
+ Short-lived, least-privilege credentials from Vault without ever passing a
4
+ Vault token across a process boundary.
5
+
6
+ from vault_approle import approle_session
7
+
8
+ with approle_session("example-ecr") as session:
9
+ with session.aws_ecr() as ecr:
10
+ ecr.docker_login()
11
+ subprocess.run(["docker", "push", image], check=True)
12
+
13
+ The four invariants this package exists to uphold are written down in
14
+ docs/contract.md and asserted in tests/contract.
15
+ """
16
+
17
+ import os
18
+
19
+ from .errors import ( # noqa: F401
20
+ AppRoleLoginError,
21
+ BootstrapCompromised,
22
+ CleanupError,
23
+ ConfigError,
24
+ EngineRoleNotFound,
25
+ ExitCode,
26
+ ProviderDenied,
27
+ ProviderNotImplemented,
28
+ ToolkitError,
29
+ VaultPermissionDenied,
30
+ )
31
+ from .session import Session, approle_session, build_session # noqa: F401
32
+
33
+
34
+ def _read_version():
35
+ """Read the VERSION file shipped beside this module.
36
+
37
+ The authored copy is ./VERSION at the repository root, which setuptools
38
+ reads for the package version. This one is generated from it by `make
39
+ sync-version` and compared against it by `make version-check`.
40
+
41
+ A second file rather than a literal, and rather than importlib.metadata,
42
+ because of where this has to answer: the image artifact is a plain
43
+ directory copy of the package with no dist-info to query and no repository
44
+ root above it. A literal would be a copy too, just one that nothing checks.
45
+
46
+ A packaging mistake that drops the file raises here rather than reporting a
47
+ placeholder. The version is what the skew check compares, so a quiet wrong
48
+ answer is worse than a loud absent one.
49
+ """
50
+ path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "VERSION")
51
+ with open(path, encoding="utf-8") as handle:
52
+ return handle.read().strip()
53
+
54
+
55
+ __version__ = _read_version()
56
+
57
+ __all__ = [
58
+ "AppRoleLoginError",
59
+ "BootstrapCompromised",
60
+ "CleanupError",
61
+ "ConfigError",
62
+ "EngineRoleNotFound",
63
+ "ExitCode",
64
+ "ProviderDenied",
65
+ "ProviderNotImplemented",
66
+ "Session",
67
+ "ToolkitError",
68
+ "VaultPermissionDenied",
69
+ "__version__",
70
+ "approle_session",
71
+ "build_session",
72
+ ]
@@ -0,0 +1,9 @@
1
+ """Authentication methods."""
2
+
3
+ from .approle import AppRoleAuth # noqa: F401
4
+ from .base import AuthMethod, available, get_auth # noqa: F401
5
+ from .token_passthrough import TokenAuth # noqa: F401
6
+
7
+ DEFAULT = "approle"
8
+
9
+ __all__ = ["AppRoleAuth", "AuthMethod", "TokenAuth", "DEFAULT", "available", "get_auth"]
@@ -0,0 +1,68 @@
1
+ """AppRole login: the default, and the reason this toolkit exists.
2
+
3
+ The client holds a RoleID (an identifier, publishable) and a SecretID scoped to
4
+ that one application. The Vault token that comes back is an intermediate value
5
+ that never leaves this process.
6
+ """
7
+
8
+ from ..bootstrap import DEFAULT as DEFAULT_BOOTSTRAP
9
+ from ..bootstrap import get_bootstrap
10
+ from ..errors import AppRoleLoginError, VaultHTTPError, VaultPermissionDenied
11
+ from ..logging import audit, get_logger
12
+ from .base import AuthMethod, register
13
+
14
+ log = get_logger("auth.approle")
15
+
16
+
17
+ @register
18
+ class AppRoleAuth(AuthMethod):
19
+ name = "approle"
20
+ owns_token = True
21
+
22
+ def __init__(self, profile, options=None):
23
+ super().__init__(profile, options)
24
+ self.bootstrap = get_bootstrap(
25
+ self.options.get("bootstrap") or DEFAULT_BOOTSTRAP,
26
+ profile=profile,
27
+ options=self.options,
28
+ )
29
+ self._secret_id = None
30
+
31
+ def authenticate(self, client):
32
+ auth_path = self.profile.vault.auth_path
33
+ role_id = self.bootstrap.role_id()
34
+ secret_id = self.bootstrap.secret_id(http=client.http)
35
+ self._secret_id = secret_id
36
+
37
+ try:
38
+ token = client.approle_login(auth_path, role_id, secret_id)
39
+ except VaultPermissionDenied as exc:
40
+ raise AppRoleLoginError(
41
+ f"approle login rejected at auth/{auth_path}/login: {exc}",
42
+ hint="the SecretID may be expired, used up, or bound to a different "
43
+ "CIDR; check with 'vault-approle doctor'",
44
+ ) from None
45
+ except VaultHTTPError as exc:
46
+ raise AppRoleLoginError(
47
+ f"approle login failed at auth/{auth_path}/login: {exc}",
48
+ hint="confirm the approle auth method is enabled at this path "
49
+ "(profile field vault.auth_path)",
50
+ ) from None
51
+ finally:
52
+ # The SecretID has done its job the moment login returns.
53
+ secret_id.wipe()
54
+
55
+ audit(
56
+ "auth.login",
57
+ method="approle",
58
+ auth_path=auth_path,
59
+ accessor=token.accessor,
60
+ policies=list(token.policies),
61
+ ttl=token.lease_duration,
62
+ )
63
+ return token
64
+
65
+ def describe(self):
66
+ info = super().describe()
67
+ info.update(self.bootstrap.describe())
68
+ return info
@@ -0,0 +1,53 @@
1
+ """Two authentication methods, and deliberately no automatic fallback.
2
+
3
+ Falling back from AppRole to a passed-in token on error would hide a security
4
+ downgrade at exactly the moment somebody should notice it. Both situations that
5
+ need the token path -- an AppRole misconfiguration being debugged, and local
6
+ development -- are moments when a human is present, so writing ``--auth token``
7
+ costs nothing and leaves a trace.
8
+ """
9
+
10
+ import abc
11
+
12
+ from ..errors import ConfigError
13
+
14
+ _REGISTRY = {}
15
+
16
+
17
+ class AuthMethod(abc.ABC):
18
+ name = None
19
+
20
+ #: True when this method created the token, which is what decides whether
21
+ #: cleanup may call revoke-self.
22
+ owns_token = True
23
+
24
+ def __init__(self, profile, options=None):
25
+ self.profile = profile
26
+ self.options = options or {}
27
+
28
+ @abc.abstractmethod
29
+ def authenticate(self, client):
30
+ """Return a :class:`~vault_approle.token.VaultToken`."""
31
+
32
+ def describe(self):
33
+ return {"auth": self.name, "owns_token": self.owns_token}
34
+
35
+
36
+ def register(cls):
37
+ _REGISTRY[cls.name] = cls
38
+ return cls
39
+
40
+
41
+ def get_auth(name, profile, options=None):
42
+ try:
43
+ cls = _REGISTRY[name]
44
+ except KeyError:
45
+ raise ConfigError(
46
+ f"unknown auth method {name!r}",
47
+ hint="available: {}".format(", ".join(sorted(_REGISTRY))),
48
+ ) from None
49
+ return cls(profile, options=options)
50
+
51
+
52
+ def available():
53
+ return sorted(_REGISTRY)
@@ -0,0 +1,70 @@
1
+ """Explicit token passthrough: a visible, recorded downgrade.
2
+
3
+ Two legitimate uses -- debugging a broken AppRole setup, and local development
4
+ against an application that has not been onboarded yet. Because the token
5
+ belongs to the caller, cleanup must never call revoke-self; only the leases
6
+ this session created get revoked.
7
+ """
8
+
9
+ import logging
10
+ import os
11
+
12
+ from ..errors import ConfigError
13
+ from ..logging import audit
14
+ from ..token import VaultToken
15
+ from .base import AuthMethod, register
16
+
17
+ # Read as a last resort under --auth token. This toolkit never writes it:
18
+ # a token on disk survives the process and is readable by every build sharing
19
+ # the agent, which is one of the leaks AppRole exists to close.
20
+ TOKEN_FILE = "~/.vault-token" # noqa: S105 - a path, not a credential
21
+
22
+
23
+ @register
24
+ class TokenAuth(AuthMethod):
25
+ name = "token"
26
+ owns_token = False
27
+
28
+ def authenticate(self, client):
29
+ value = self.options.get("token") or os.environ.get("VAULT_TOKEN")
30
+ source = "cli" if self.options.get("token") else "env:VAULT_TOKEN"
31
+
32
+ if not value:
33
+ path = os.path.expanduser(TOKEN_FILE)
34
+ if os.path.exists(path):
35
+ with open(path, encoding="utf-8") as handle:
36
+ value = handle.read().strip()
37
+ source = TOKEN_FILE
38
+
39
+ if not value:
40
+ raise ConfigError(
41
+ "--auth token needs a token",
42
+ hint="set VAULT_TOKEN, or drop --auth token to use AppRole",
43
+ )
44
+
45
+ token = VaultToken(value)
46
+ try:
47
+ info = client.lookup_self(token)
48
+ except Exception: # noqa: BLE001 - lookup is informational only
49
+ info = {}
50
+
51
+ # WARNING, not INFO: running on a caller-supplied token is a downgrade
52
+ # and should be visible at the default log level.
53
+ audit(
54
+ "auth.login",
55
+ level=logging.WARNING,
56
+ method="token",
57
+ source=source,
58
+ degraded=True,
59
+ policies=info.get("policies"),
60
+ ttl=info.get("ttl"),
61
+ )
62
+ token.policies = tuple(info.get("policies") or ())
63
+ token.lease_duration = int(info.get("ttl") or 0)
64
+ token.accessor = info.get("accessor")
65
+ return token
66
+
67
+ def describe(self):
68
+ info = super().describe()
69
+ info["degraded"] = True
70
+ return info
@@ -0,0 +1,19 @@
1
+ """SecretID bootstrap methods."""
2
+
3
+ from .base import Bootstrap, available, get_bootstrap # noqa: F401
4
+ from .env import EnvBootstrap, resolve_role_id # noqa: F401
5
+ from .file import FileBootstrap # noqa: F401
6
+ from .wrapped import WrappedBootstrap # noqa: F401
7
+
8
+ DEFAULT = "env"
9
+
10
+ __all__ = [
11
+ "Bootstrap",
12
+ "EnvBootstrap",
13
+ "FileBootstrap",
14
+ "WrappedBootstrap",
15
+ "DEFAULT",
16
+ "available",
17
+ "get_bootstrap",
18
+ "resolve_role_id",
19
+ ]
@@ -0,0 +1,58 @@
1
+ """How the client gets hold of its SecretID.
2
+
3
+ Three sources, deliberately no fourth. In particular there is no "rotating"
4
+ source: consume-one-mint-one needs shared mutable state that every consumer can
5
+ write to, and a crash between "minted" and "written back" breaks the chain and
6
+ needs a human. On-demand issuance gets the same single-use property with no
7
+ state at all, so that is where this is headed.
8
+ """
9
+
10
+ import abc
11
+
12
+ from ..errors import BootstrapError
13
+
14
+ _REGISTRY = {}
15
+
16
+
17
+ class Bootstrap(abc.ABC):
18
+ """Resolves RoleID and SecretID from somewhere outside the process."""
19
+
20
+ #: Value accepted by --bootstrap.
21
+ name = None
22
+
23
+ def __init__(self, profile=None, options=None):
24
+ self.profile = profile
25
+ self.options = options or {}
26
+
27
+ @abc.abstractmethod
28
+ def secret_id(self, http=None):
29
+ """Return a :class:`~vault_approle.token.SecretString`."""
30
+
31
+ def role_id(self):
32
+ """RoleID is an identifier, not a credential, so the lookup is shared."""
33
+ from .env import resolve_role_id # noqa: PLC0415 - avoids an import cycle
34
+
35
+ return resolve_role_id(self.options, self.profile)
36
+
37
+ def describe(self):
38
+ return {"bootstrap": self.name}
39
+
40
+
41
+ def register(cls):
42
+ _REGISTRY[cls.name] = cls
43
+ return cls
44
+
45
+
46
+ def get_bootstrap(name, profile=None, options=None):
47
+ try:
48
+ cls = _REGISTRY[name]
49
+ except KeyError:
50
+ raise BootstrapError(
51
+ f"unknown bootstrap method {name!r}",
52
+ hint="available: {}".format(", ".join(sorted(_REGISTRY))),
53
+ ) from None
54
+ return cls(profile=profile, options=options)
55
+
56
+
57
+ def available():
58
+ return sorted(_REGISTRY)
@@ -0,0 +1,108 @@
1
+ """SecretID from the environment. This is how Jenkins injects it in phase one.
2
+
3
+ One long-lived SecretID per application, not rotated. Tightening happens on the
4
+ Vault side instead: bind ``secret_id_bound_cidrs`` to the agent network, keep
5
+ ``token_ttl`` short, and revoke a single accessor when one application needs to
6
+ be cut off without disturbing the others.
7
+
8
+ The variable name is configurable rather than fixed. An agent that brokers for
9
+ several applications has to keep their SecretIDs apart, and renaming ours is
10
+ cheaper than asking every one of them to standardise on ``VAULT_SECRET_ID``.
11
+ """
12
+
13
+ import os
14
+
15
+ from ..errors import BootstrapError, ConfigError
16
+ from ..token import SecretString
17
+ from .base import Bootstrap, register
18
+
19
+ DEFAULT_SECRET_ID_VAR = "VAULT_SECRET_ID" # noqa: S105 - a variable name, not a value
20
+ DEFAULT_ROLE_ID_VAR = "VAULT_ROLE_ID"
21
+
22
+
23
+ def secret_id_var(options):
24
+ """Which variable holds the SecretID.
25
+
26
+ Also used as the key to look for in a ``KEY=VALUE`` file, because a file
27
+ holding ``VAULT_SECRET_ID=...`` is the same variable arriving by another
28
+ route.
29
+ """
30
+ return _registered((options or {}).get("secret_id_env") or DEFAULT_SECRET_ID_VAR)
31
+
32
+
33
+ def role_id_var(options):
34
+ return _registered((options or {}).get("role_id_env") or DEFAULT_ROLE_ID_VAR)
35
+
36
+
37
+ def _registered(name):
38
+ """Keep invariant 2 honest when the variable has been renamed.
39
+
40
+ Child environments are stripped by the ``VAULT_`` prefix, which cannot see
41
+ a name like ``MY_APP_SECRET_ID``. Telling the delivery layer about it
42
+ here means the rename does not quietly punch a hole in the guarantee.
43
+ """
44
+ from ..delivery.subprocess_env import register_stripped # noqa: PLC0415 - import cycle
45
+
46
+ register_stripped(name)
47
+ return name
48
+
49
+
50
+ @register
51
+ class EnvBootstrap(Bootstrap):
52
+ name = "env"
53
+
54
+ ENV_VAR = DEFAULT_SECRET_ID_VAR
55
+
56
+ @property
57
+ def env_var(self):
58
+ return secret_id_var(self.options)
59
+
60
+ def secret_id(self, http=None):
61
+ name = self.env_var
62
+ value = self.options.get("secret_id") or os.environ.get(name)
63
+ if not value:
64
+ raise BootstrapError(
65
+ f"{name} is not set",
66
+ hint="inject the application's SecretID as a masked CI credential, "
67
+ "or switch to --bootstrap file / --bootstrap wrapped",
68
+ )
69
+ return SecretString(value.strip(), origin=f"env:{name}")
70
+
71
+ def describe(self):
72
+ return {"bootstrap": self.name, "env_var": self.env_var}
73
+
74
+
75
+ def resolve_role_id(options=None, profile=None):
76
+ """RoleID from CLI, env, a file, or the profile.
77
+
78
+ Not a secret, so no SecretString and no redaction. Precedence matches
79
+ everything else: CLI > environment > file > profile.
80
+
81
+ The profile is the interesting one. A RoleID identifies a role rather than
82
+ authorising anything, and one AppRole has a single RoleID that every
83
+ consumer shares -- so it is a constant of the deployment, and a deployment
84
+ constant belongs in the profile next to the auth path it names.
85
+ """
86
+ options = options or {}
87
+ name = role_id_var(options)
88
+
89
+ value = options.get("role_id") or os.environ.get(name)
90
+ if value:
91
+ return value.strip()
92
+
93
+ path = options.get("role_id_file") or os.environ.get(f"{name}_FILE")
94
+ if path:
95
+ from .file import read_key_value_file # noqa: PLC0415 - avoids an import cycle
96
+
97
+ return read_key_value_file(path, name, enforce_mode=False)
98
+
99
+ from_profile = getattr(getattr(profile, "vault", None), "role_id", None)
100
+ if from_profile:
101
+ return str(from_profile).strip()
102
+
103
+ raise ConfigError(
104
+ "no role id available",
105
+ hint=f"set {name}, {name}_FILE, pass --role-id, or put vault.role_id in "
106
+ "the profile; the RoleID is an identifier rather than a secret, so the "
107
+ "profile is a reasonable home for it",
108
+ )
@@ -0,0 +1,103 @@
1
+ """SecretID from a file on disk.
2
+
3
+ Accepts both a bare single-line value and a ``KEY=VALUE`` layout
4
+ (``VAULT_SECRET_ID=...``), so a file maintained by an existing renewal job can be
5
+ read as-is.
6
+ """
7
+
8
+ import os
9
+ import stat
10
+
11
+ from ..errors import BootstrapError
12
+ from ..logging import get_logger
13
+ from ..token import SecretString
14
+ from .base import Bootstrap, register
15
+ from .env import secret_id_var
16
+
17
+ log = get_logger("bootstrap.file")
18
+
19
+ DEFAULT_PATHS = ("/etc/vault-approle/secret-id",)
20
+
21
+
22
+ @register
23
+ class FileBootstrap(Bootstrap):
24
+ name = "file"
25
+
26
+ def secret_id(self, http=None):
27
+ # The same name identifies the variable whether it arrives through the
28
+ # environment or as a KEY=VALUE line, so --secret-id-env renames both.
29
+ name = secret_id_var(self.options)
30
+ path = self._path(name)
31
+ if not path:
32
+ raise BootstrapError(
33
+ "no secret id file given",
34
+ hint=f"pass --secret-id-file or set {name}_FILE",
35
+ )
36
+ value = read_key_value_file(path, name)
37
+ return SecretString(value, origin=f"file:{path}")
38
+
39
+ def _path(self, name):
40
+ return (
41
+ self.options.get("secret_id_file")
42
+ or os.environ.get(f"{name}_FILE")
43
+ or self._first_default()
44
+ )
45
+
46
+ @staticmethod
47
+ def _first_default():
48
+ for candidate in DEFAULT_PATHS:
49
+ if os.path.exists(candidate):
50
+ return candidate
51
+ return None
52
+
53
+ def describe(self):
54
+ name = secret_id_var(self.options)
55
+ return {"bootstrap": self.name, "key": name, "path": self._path(name)}
56
+
57
+
58
+ def read_key_value_file(path, key, enforce_mode=True):
59
+ """Read ``key`` out of a file, or the whole file if it holds a bare value."""
60
+ path = os.path.expanduser(path)
61
+ if not os.path.exists(path):
62
+ raise BootstrapError(
63
+ f"secret file not found: {path}",
64
+ hint="check the path, or use --bootstrap env",
65
+ )
66
+
67
+ if enforce_mode:
68
+ _warn_on_loose_permissions(path)
69
+
70
+ try:
71
+ with open(path, encoding="utf-8") as handle:
72
+ content = handle.read()
73
+ except OSError as exc:
74
+ raise BootstrapError(f"cannot read {path}: {exc}") from None
75
+
76
+ for line in content.splitlines():
77
+ line = line.strip()
78
+ if not line or line.startswith("#"):
79
+ continue
80
+ if "=" in line:
81
+ name, _, value = line.partition("=")
82
+ if name.strip() == key:
83
+ return value.strip().strip("'\"")
84
+ elif len(content.strip().splitlines()) == 1:
85
+ # A bare single-line file.
86
+ return line
87
+
88
+ raise BootstrapError(
89
+ f"{path} does not contain {key}",
90
+ hint=f"expected a bare value or a line of the form {key}=<value>",
91
+ )
92
+
93
+
94
+ def _warn_on_loose_permissions(path):
95
+ try:
96
+ mode = os.stat(path).st_mode
97
+ except OSError:
98
+ return
99
+ if mode & (stat.S_IRWXG | stat.S_IRWXO):
100
+ log.warning(
101
+ "secret file has permissions readable beyond its owner",
102
+ extra={"fields": {"path": path, "mode": oct(stat.S_IMODE(mode))}},
103
+ )
@@ -0,0 +1,101 @@
1
+ """SecretID delivered as a response-wrapped payload.
2
+
3
+ The issuer calls ``.../secret-id`` with ``X-Vault-Wrap-TTL``. Vault stores the
4
+ SecretID in a single-use cubbyhole and hands back a wrapping token that can do
5
+ exactly one thing -- ``sys/wrapping/unwrap`` -- and only once.
6
+
7
+ The property that matters is not "cannot be stolen" but "cannot be stolen
8
+ unnoticed": if an attacker unwraps first, our unwrap fails. That is a
9
+ disclosure signal, so it gets its own exit code (60) and a loud message instead
10
+ of a retry.
11
+
12
+ Phase one implements the consumer side only. Wrapping stays a manual step until
13
+ a deployment system can do it as part of triggering a deploy, which is the
14
+ model this is aimed at: wrap on demand, hand the unwrap token to the deploy,
15
+ and the credential never sits around waiting to be used.
16
+ """
17
+
18
+ import logging
19
+ import os
20
+
21
+ from ..errors import BootstrapCompromised, BootstrapError, VaultHTTPError
22
+ from ..logging import audit
23
+ from ..token import SecretString
24
+ from .base import Bootstrap, register
25
+
26
+
27
+ @register
28
+ class WrappedBootstrap(Bootstrap):
29
+ name = "wrapped"
30
+
31
+ ENV_VAR = "VAULT_WRAPPED_SECRET_ID"
32
+
33
+ @property
34
+ def env_var(self):
35
+ name = self.options.get("wrapping_token_env") or self.ENV_VAR
36
+ # See bootstrap/env.py: a renamed variable is invisible to the VAULT_
37
+ # prefix rule that strips child environments.
38
+ from ..delivery.subprocess_env import register_stripped # noqa: PLC0415
39
+
40
+ register_stripped(name)
41
+ return name
42
+
43
+ def _wrapping_token(self):
44
+ name = self.env_var
45
+ value = self.options.get("wrapping_token") or os.environ.get(name)
46
+ if value:
47
+ return value.strip()
48
+
49
+ path = self.options.get("wrapping_token_file") or os.environ.get(f"{name}_FILE")
50
+ if path:
51
+ from .file import read_key_value_file # noqa: PLC0415 - avoids an import cycle
52
+
53
+ return read_key_value_file(path, name)
54
+
55
+ raise BootstrapError(
56
+ f"{name} is not set",
57
+ hint="wrap a SecretID with: vault write -wrap-ttl=90s -f "
58
+ "auth/<path>/role/<role>/secret-id",
59
+ )
60
+
61
+ def secret_id(self, http=None):
62
+ if http is None:
63
+ raise BootstrapError("the wrapped bootstrap needs a vault connection")
64
+
65
+ token = self._wrapping_token()
66
+ try:
67
+ # No retries: the token is single-use, so a retry can only ever add
68
+ # a confusing second failure.
69
+ response = http.post("sys/wrapping/unwrap", token=token, payload={}, retries=0)
70
+ except VaultHTTPError as exc:
71
+ raise self._compromise_error(exc) from None
72
+ except Exception as exc: # noqa: BLE001 - every unwrap failure is the same signal
73
+ raise self._compromise_error(exc) from None
74
+
75
+ value = (response.data or {}).get("secret_id")
76
+ if not value:
77
+ raise BootstrapError(
78
+ "the unwrapped payload has no secret_id field",
79
+ hint="the wrapping token wrapped something other than a SecretID",
80
+ )
81
+
82
+ audit("bootstrap.unwrap", result="ok")
83
+ return SecretString(value, origin="wrapped")
84
+
85
+ @staticmethod
86
+ def _compromise_error(cause):
87
+ audit(
88
+ "bootstrap.unwrap",
89
+ level=logging.WARNING,
90
+ result="failed",
91
+ detail=str(cause),
92
+ )
93
+ return BootstrapCompromised(
94
+ f"the wrapping token could not be unwrapped: {cause}",
95
+ hint="a wrapping token is single-use. Either it expired, or somebody "
96
+ "unwrapped it first -- treat the second case as a disclosure: destroy "
97
+ "the SecretID accessor and re-issue.",
98
+ )
99
+
100
+ def describe(self):
101
+ return {"bootstrap": self.name, "env_var": self.env_var, "single_use": True}
@@ -0,0 +1,5 @@
1
+ """Command line interface."""
2
+
3
+ from .main import main # noqa: F401
4
+
5
+ __all__ = ["main"]