vaultctl 0.1.0__py3-none-any.whl

vaultctl/commands/__init__.py

@@ -0,0 +1,15 @@
+import typer
+
+from vaultctl.commands.backup_raft_snapshot import app as backup_raft_snapshot
+from vaultctl.commands.bootstrap import app as bootstrap
+from vaultctl.commands.login import app as login
+from vaultctl.commands.pki.rotate_issuing import app as pki
+from vaultctl.commands.restore_raft_snapshot import app as restore_raft_snapshot
+
+app = typer.Typer()
+
+app.add_typer(bootstrap)
+app.add_typer(restore_raft_snapshot)
+app.add_typer(backup_raft_snapshot)
+app.add_typer(login)
+app.add_typer(pki)

vaultctl/commands/backup_raft_snapshot.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import datetime
+import hashlib
+import io
+import tarfile
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, cast
+
+import hvac
+import typer
+from botocore.exceptions import ClientError
+from requests import Response
+
+from vaultctl.options import (
+    AddressOption,
+    AwsAccessKeyIdOption,
+    AwsEndpointUrlOption,
+    AwsProfileOption,
+    AwsRegionOption,
+    AwsSecretAccessKeyOption,
+    CACertOption,
+    CAPathOption,
+    K8sMountPointOption,
+    K8sRoleOption,
+    OutputFileOption,
+    S3BucketNameOption,
+    S3KeyPrefixOption,
+    SkipVerifyOption,
+    TimeoutOption,
+    TokenOption,
+)
+from vaultctl.utils import handle_s3_authentication, handle_vault_authentication, logger
+
+app = typer.Typer()
+
+
+class RaftUploadError(Exception):
+    """Raised when uploading a Raft snapshot to S3 fails."""
+
+
+class S3ChecksumAlgorithm(Enum):
+    CRC32 = "CRC32"
+    CRC32C = "CRC32C"
+    SHA1 = "SHA1"
+    SHA256 = "SHA256"
+    CRC64NVME = "CRC64NVME"
+
+
+def parse_sha256sums(content: bytes) -> dict[str, str]:
+    sums = {}
+    lines = content.strip().split(b"\n")
+    for line in lines:
+        trimmed_line = line.strip()
+        if not trimmed_line:
+            continue
+        parts = trimmed_line.split()
+        if len(parts) == 2:  # noqa: PLR2004
+            checksum = parts[0].decode("utf-8")
+            filename = parts[1].decode("utf-8")
+            sums[filename] = checksum
+    return sums
+
+
+def verify_internal_checksums(snapshot_data: bytes) -> None:
+    logger.info("Verifying snapshot integrity...")
+    snapshot_stream = io.BytesIO(snapshot_data)
+
+    try:
+        with tarfile.open(fileobj=snapshot_stream, mode="r:gz") as tar:
+            sha_sums_content = None
+            files_in_tar: dict[str, bytes] = {}
+
+            for member in tar.getmembers():
+                if not member.isfile():
+                    continue
+
+                if not (f := tar.extractfile(member)):
+                    continue
+
+                content = f.read()
+
+                if member.name == "SHA256SUMS":
+                    sha_sums_content = content
+
+                files_in_tar[member.name] = content
+
+            if sha_sums_content is None:
+                msg = "SHA256SUMS file not found in the Raft snapshot archive."
+                raise ValueError(
+                    msg,
+                )
+
+            expected_sums = parse_sha256sums(sha_sums_content)
+
+            for name, expected_sum in expected_sums.items():
+                content = files_in_tar.get(name)
+
+                if content is None:
+                    msg = f"file '{name}' listed in SHA256SUMS not found in archive."
+                    raise ValueError(
+                        msg,
+                    )
+
+                computed_sum = hashlib.sha256(content).hexdigest()
+
+                if computed_sum != expected_sum:
+                    msg = f"checksum mismatch for file '{name}'. Expected: {expected_sum}, Got: {computed_sum}"
+                    raise ValueError(
+                        msg,
+                    )
+
+            logger.info("Snapshot integrity verified.")
+
+    except tarfile.TarError as e:
+        msg = f"reading archive: {e}"
+        raise tarfile.TarError(msg) from e
+
+
+@app.command(
+    help="Executes a complete workflow for obtaining a HashiCorp Vault Raft snapshot from a cluster, verifying its integrity, and uploading it securely to S3 storage. Provides flexible authentication options for both HashiCorp Vault and S3 APIs.",
+)
+def backup_raft_snapshot(  # noqa: PLR0913
+    address: AddressOption,
+    s3_bucket_name: S3BucketNameOption = None,
+    output_file: OutputFileOption = None,
+    k8s_role: K8sRoleOption = None,
+    k8s_mount_point: K8sMountPointOption = "kubernetes",
+    token: TokenOption = None,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
+    aws_profile: AwsProfileOption = None,
+    aws_access_key_id: AwsAccessKeyIdOption = None,
+    aws_secret_access_key: AwsSecretAccessKeyOption = None,
+    aws_endpoint_url: AwsEndpointUrlOption = None,
+    aws_region: AwsRegionOption = "us-east-1",
+    s3_key_prefix: S3KeyPrefixOption = "",
+    s3_checksum_algorithm: Annotated[
+        S3ChecksumAlgorithm,
+        typer.Option(help="The algorithm to use for s3 transport checksum."),
+    ] = S3ChecksumAlgorithm.CRC64NVME,
+    timeout: TimeoutOption = 30,
+    *,
+    skip_verify: SkipVerifyOption = False,
+) -> None:
+    if not s3_bucket_name and not output_file:
+        msg = "Either --s3-bucket-name or --output-file is required"
+        raise typer.BadParameter(msg)
+
+    vault_client = handle_vault_authentication(
+        hvac.Client(
+            url=address,
+            timeout=timeout,
+            verify=(
+                str(ca_cert)
+                if ca_cert
+                else str(ca_path)
+                if ca_path
+                else (not skip_verify)
+            ),
+        ),
+        token=token,
+        k8s_role=k8s_role,
+        k8s_mount_point=k8s_mount_point,
+    )
+
+    if vault_client.sys.is_sealed():
+        logger.error("Vault is sealed. Cannot proceed with backup.")
+        raise typer.Exit(code=1)
+
+    logger.info("Starting backup...")
+
+    logger.info("Requesting raft snapshot...")
+    response: Response = vault_client.sys.take_raft_snapshot()
+
+    if response.status_code != 200:  # noqa: PLR2004
+        logger.error(
+            "Raft snapshot request failed with status code %s.",
+            response.status_code,
+        )
+        logger.debug("Response body: %s", response.text)
+        raise typer.Exit(1)
+
+    snapshot_data: bytes = response.content
+
+    logger.info("Raft snapshot retrieved.")
+
+    try:
+        verify_internal_checksums(snapshot_data)
+    except (tarfile.TarError, ValueError):
+        logger.exception("Verifying raft snapshot integrity")
+        raise typer.Exit(1) from None
+
+    if output_file:
+        output_path = Path(output_file)
+        if output_path.is_dir():
+            timestamp = datetime.datetime.now(tz=datetime.UTC).strftime("%Y%m%d_%H%M%S")
+            output_path = output_path / f"vault-snapshot-{timestamp}.snap"
+        output_path.write_bytes(snapshot_data)
+        logger.info("Snapshot written to %s", output_path)
+        logger.info("Backup completed")
+        return
+
+    s3_bucket_name = cast("str", s3_bucket_name)
+
+    s3_client = handle_s3_authentication(
+        bucket_name=s3_bucket_name,
+        aws_access_key_id=aws_access_key_id,
+        aws_secret_access_key=aws_secret_access_key,
+        aws_region=aws_region,
+        aws_profile=aws_profile,
+        endpoint_url=aws_endpoint_url,
+    )
+
+    timestamp = datetime.datetime.now(tz=datetime.UTC).strftime("%Y%m%d_%H%M%S")
+    snapshot_name = f"vault-snapshot-{timestamp}.snap"
+    s3_key = f"{s3_key_prefix}{snapshot_name}"
+
+    try:
+        logger.info("Uploading raft snapshot to %s/%s...", s3_bucket_name, s3_key)
+        s3_client.upload_fileobj(
+            io.BytesIO(snapshot_data),
+            s3_bucket_name,
+            s3_key,
+            ExtraArgs={
+                "ContentType": "application/gzip",
+                "ChecksumAlgorithm": s3_checksum_algorithm,
+            },
+        )
+    except ClientError:
+        logger.exception("Uploading raft snapshot")
+        raise typer.Exit(1) from None
+
+    logger.info("Raft snapshot uploaded.")
+    logger.info("Backup completed")

vaultctl/commands/bootstrap.py

@@ -0,0 +1,125 @@
+import time
+from typing import Any
+
+import hvac
+import typer
+
+from vaultctl.commands.restore_raft_snapshot import restore_raft_snapshot
+from vaultctl.options import (
+    AddressOption,
+    AwsAccessKeyIdOption,
+    AwsEndpointUrlOption,
+    AwsProfileOption,
+    AwsRegionOption,
+    AwsSecretAccessKeyOption,
+    CACertOption,
+    CAPathOption,
+    S3BucketNameOption,
+    S3KeyPrefixOption,
+    SkipVerifyOption,
+    SnapshotFileOption,
+    SnapshotNameOption,
+    SnapshotNameRegexOption,
+    TimeoutOption,
+)
+
+app = typer.Typer()
+
+AUTO_UNSEAL_MAX_ATTEMPT = 10
+
+
+@app.command(
+    help="Init, unseal and force restore a hashicorp vault cluster from S3 storage using raft snapshots",
+)
+def bootstrap(  # noqa: PLR0913
+    ctx: typer.Context,
+    address: AddressOption,
+    s3_bucket_name: S3BucketNameOption = None,
+    snapshot_file: SnapshotFileOption = None,
+    *,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
+    skip_verify: SkipVerifyOption = False,
+    s3_key_prefix: S3KeyPrefixOption = "",
+    filename: SnapshotNameOption = None,
+    filename_regex: SnapshotNameRegexOption = None,
+    aws_profile: AwsProfileOption = None,
+    aws_access_key_id: AwsAccessKeyIdOption = None,
+    aws_secret_access_key: AwsSecretAccessKeyOption = None,
+    aws_endpoint_url: AwsEndpointUrlOption = None,
+    aws_region: AwsRegionOption = "us-east-1",
+    timeout: TimeoutOption = 30,
+) -> None:
+    if not s3_bucket_name and not snapshot_file:
+        msg = "Either --s3-bucket-name or --snapshot-file is required"
+        raise typer.BadParameter(msg)
+    client = hvac.Client(
+        url=address,
+        timeout=timeout,
+        verify=(
+            str(ca_cert) if ca_cert else str(ca_path) if ca_path else (not skip_verify)
+        ),
+    )
+
+    if not client.sys.is_initialized():
+        typer.echo("Vault is not initialized. Starting bootstrap procedure...")
+        seal_status: dict[str, Any] = client.sys.read_seal_status()
+        seal_type = seal_status["type"]
+
+        is_kms = seal_type != "shamir"
+
+        if is_kms:
+            typer.echo(
+                f"Detected Auto-Unseal ({seal_type}). Initializing with recovery keys...",
+            )
+            result = client.sys.initialize(recovery_shares=5, recovery_threshold=3)
+            typer.echo("Successfully initialized with Auto-Unseal.")
+        else:
+            typer.echo("Detected Shamir seal. Initializing with secret shares...")
+            result = client.sys.initialize(secret_shares=5, secret_threshold=3)
+            typer.echo("Successfully initialized with Shamir seal.")
+
+        root_token = result["root_token"]
+        client.token = root_token
+
+        if not is_kms:
+            typer.echo("Unsealing with Shamir keys...")
+            keys = result["keys"]
+            client.sys.submit_unseal_keys(keys)
+        else:
+            typer.echo("Waiting for Auto-Unseal to complete...")
+            attempts = 0
+            while client.sys.is_sealed() and attempts < AUTO_UNSEAL_MAX_ATTEMPT:
+                time.sleep(1)
+                attempts += 1
+
+            if client.sys.is_sealed():
+                typer.echo(
+                    "Error: Vault is still sealed after Auto-Unseal init. Check Vault logs.",
+                )
+                raise typer.Exit(code=1)
+
+        typer.echo("Vault is unsealed and ready. Starting restore...")
+
+        restore_raft_snapshot(
+            ctx=ctx,
+            address=address,
+            ca_cert=ca_cert,
+            ca_path=ca_path,
+            skip_verify=skip_verify,
+            s3_bucket_name=s3_bucket_name,
+            snapshot_file=snapshot_file,
+            s3_key_prefix=s3_key_prefix,
+            filename=filename,
+            filename_regex=filename_regex,
+            aws_profile=aws_profile,
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            aws_endpoint_url=aws_endpoint_url,
+            aws_region=aws_region,
+            force_restore=True,
+            timeout=timeout,
+            token=root_token,
+        )
+    else:
+        typer.echo("Vault already initialized. Skipping bootstrap procedure.")

vaultctl/commands/login.py

@@ -0,0 +1,122 @@
+from pathlib import Path
+from typing import Annotated, Literal
+
+import hvac
+import typer
+from hvac.exceptions import InvalidRequest, VaultError
+from rich.console import Console
+from rich.table import Table
+
+from vaultctl.options import (
+    AddressOption,
+    CACertOption,
+    CAPathOption,
+    SkipVerifyOption,
+)
+
+
+def format_lease_duration(seconds: int) -> str:
+    hours, remainder = divmod(seconds, 3600)
+    minutes, secs = divmod(remainder, 60)
+    return f"{hours}h{minutes}m{secs}s"
+
+
+TOKEN_FILE = Path.home() / ".vault-token"
+
+app = typer.Typer()
+
+
+@app.command(help="Authenticate with Vault and optionally save the token.")
+def login(  # noqa: C901, PLR0913
+    ctx: typer.Context,  # noqa: ARG001
+    address: AddressOption,
+    *,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
+    skip_verify: SkipVerifyOption = False,
+    method: Annotated[
+        Literal["token", "userpass"],
+        typer.Option(help="Auth method: token (default) or userpass"),
+    ] = "token",
+    no_store: Annotated[
+        bool,
+        typer.Option(help="Do not persist the token to disk", is_flag=True),
+    ] = False,
+    params: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Auth parameters as key=value, like username=alice password=foo",
+        ),
+    ] = None,
+) -> None:
+    kv = {}
+    if params:
+        for p in params:
+            if "=" not in p:
+                msg = f"Invalid argument '{p}', expected key=value"
+                raise typer.BadParameter(msg)
+            k, v = p.split("=", 1)
+            kv[k] = v
+
+    client = hvac.Client(
+        url=address,
+        verify=(
+            str(ca_cert) if ca_cert else str(ca_path) if ca_path else (not skip_verify)
+        ),
+    )
+
+    username = kv.get("username")
+    password = kv.get("password")
+    token = kv.get("token")
+
+    if method == "userpass" and not username:
+        msg = "'username' must be specified"
+        raise typer.BadParameter(msg)
+
+    try:
+        if method == "token":
+            if not token:
+                token = typer.prompt(
+                    "Token (will be hidden)",
+                    hide_input=True,
+                    type=str,
+                )
+            client.token = token
+            lookup = client.auth.token.lookup_self()
+            token_info = lookup["data"]
+
+        elif method == "userpass":
+            if not password:
+                password = typer.prompt(
+                    "Password (will be hidden)",
+                    hide_input=True,
+                    type=str,
+                )
+            auth_resp = client.auth.userpass.login(username=username, password=password)
+            token_info = auth_resp["auth"]
+            client.token = token_info.get("client_token")
+
+    except (VaultError, InvalidRequest) as e:
+        typer.secho(f"Vault Error: {e}", fg="red", err=True)
+        raise typer.Exit(code=1) from None
+
+    token = token_info.get("client_token") or token_info.get("id")
+    accessor = token_info.get("accessor", "n/a")
+    ttl = token_info.get("lease_duration") or token_info.get("ttl", 0)
+    renewable = token_info.get("renewable", False)
+    metadata = token_info.get("metadata") or token_info.get("meta") or {}
+
+    if not no_store and client.token:
+        TOKEN_FILE.write_text(client.token)
+
+    console = Console()
+    table = Table("Key", "Value")
+    table.add_row("token", token)
+    table.add_row("token_accessor", accessor)
+    table.add_row("token_duration", format_lease_duration(ttl))
+    table.add_row("token_renewable", str(renewable))
+    table.add_row("token_policies", str(token_info.get("token_policies", [])))
+    table.add_row("identity_policies", str(token_info.get("identity_policies", [])))
+    table.add_row("policies", str(token_info.get("policies", [])))
+    table.add_row("token_meta_username", metadata.get("username", "n/a"))
+    console.print(table)

vaultctl/commands/pki/rotate_issuing.py

@@ -0,0 +1,155 @@
+from typing import TYPE_CHECKING, Annotated
+
+import hvac
+import typer
+from cryptography import x509
+from cryptography.hazmat.backends import default_backend
+from hvac.exceptions import InvalidPath, InvalidRequest, VaultError
+from requests import Response
+
+from vaultctl.options import (
+    AddressOption,
+    CACertOption,
+    CAPathOption,
+    SkipVerifyOption,
+    TokenOption,
+)
+from vaultctl.utils import handle_vault_authentication
+
+if TYPE_CHECKING:
+    from typing import Any
+
+app = typer.Typer()
+
+
+def to_dict(resp: dict[str, Any] | Response | None) -> dict[str, Any]:
+    if isinstance(resp, Response):
+        return resp.json()
+    if resp is None:
+        return {}
+    return resp
+
+
+@app.command()
+def rotate_issuing(  # noqa: PLR0913
+    ctx: typer.Context,  # noqa: ARG001
+    address: AddressOption,
+    token: TokenOption = None,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
+    *,
+    skip_verify: SkipVerifyOption = False,
+    iss_mount: Annotated[
+        str,
+        typer.Option(help="Vault PKI mount path for the target issuer."),
+    ],
+    int_mount: Annotated[
+        str,
+        typer.Option(
+            help="Vault PKI mount path for the intermediate CA that signs the CSR.",
+        ),
+    ],
+    common_name: Annotated[
+        str,
+        typer.Option(help="Common name for the new certificate."),
+    ],
+    ttl: Annotated[
+        str,
+        typer.Option(help="Time-to-live for the new certificate."),
+    ] = "8760h",
+    country: Annotated[
+        str,
+        typer.Option(help="Country name for the certificate subject."),
+    ] = "Bulgaria",
+    locality: Annotated[
+        str,
+        typer.Option(help="Locality name for the certificate subject."),
+    ] = "Sofia",
+    organization: Annotated[
+        str,
+        typer.Option(help="Organization name for the certificate subject."),
+    ] = "DarkfellaNET",
+) -> None:
+    vault_client = handle_vault_authentication(
+        hvac.Client(
+            url=address,
+            verify=(
+                str(ca_cert)
+                if ca_cert
+                else str(ca_path)
+                if ca_path
+                else (not skip_verify)
+            ),
+        ),
+        token=token,
+    )
+
+    if vault_client.sys.is_sealed():
+        typer.secho("Vault is sealed. Cannot proceed..", fg=typer.colors.RED, bold=True)
+        raise typer.Exit(code=1)
+
+    try:
+        typer.echo("Generating CSR using existing key material...")
+        generate_resp = to_dict(
+            vault_client.write(
+                f"{iss_mount}/issuers/generate/intermediate/existing",
+                common_name=common_name,
+                country=country,
+                locality=locality,
+                organization=organization,
+                format="pem_bundle",
+                wrap_ttl=None,
+            ),
+        )
+        csr = generate_resp["data"]["csr"]
+    except (VaultError, InvalidRequest) as e:
+        typer.echo(f"Failed to generate CSR: {e}")
+        raise
+
+    try:
+        typer.echo("Signing CSR with intermediate CA...")
+        sign_resp = to_dict(
+            vault_client.write(
+                f"{int_mount}/root/sign-intermediate",
+                csr=csr,
+                ttl=ttl,
+                wrap_ttl=None,
+            ),
+        )
+        signed_cert = sign_resp["data"]["certificate"]
+    except (VaultError, InvalidRequest) as e:
+        typer.echo(f"Failed to sign CSR: {e}")
+        raise
+
+    try:
+        typer.echo(f"Importing signed certificate back into {iss_mount}...")
+        import_resp = to_dict(
+            vault_client.write(
+                f"{iss_mount}/intermediate/set-signed",
+                certificate=signed_cert,
+                wrap_ttl=None,
+            ),
+        )
+        imported_issuers = import_resp.get("data", {}).get("imported_issuers", [])
+        if not imported_issuers:
+            msg = "Vault did not return an imported issuer ID!"
+            raise RuntimeError(msg)
+        new_issuer_id = imported_issuers[0]
+
+        vault_client.write(
+            f"{iss_mount}/config/issuers",
+            default=new_issuer_id,
+            wrap_ttl=None,
+        )
+        typer.echo(f"New issuer {new_issuer_id} set as default")
+    except (VaultError, InvalidRequest, InvalidPath) as e:
+        typer.echo(f"Failed to import signed certificate: {e}")
+        raise
+
+    cert = x509.load_pem_x509_certificate(signed_cert.encode(), default_backend())
+    typer.echo("\nNew Issuing CA info:")
+    typer.echo(f"  Subject: {cert.subject.rfc4514_string()}")
+    typer.echo(f"  Serial: {cert.serial_number}")
+    typer.echo(f"  Expires: {cert.not_valid_after.isoformat()} UTC")
+
+    typer.echo("Done! Issuing CA successfully reissued and set as default.")

vaultctl/commands/restore_raft_snapshot.py

@@ -0,0 +1,210 @@
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+import botocore.exceptions
+import hvac
+import typer
+from dateutil.parser import parse as parse_datetime
+from hvac.api.system_backend import Raft
+from hvac.exceptions import InvalidRequest, VaultError
+
+from vaultctl.options import (
+    AddressOption,
+    AwsAccessKeyIdOption,
+    AwsEndpointUrlOption,
+    AwsProfileOption,
+    AwsRegionOption,
+    AwsSecretAccessKeyOption,
+    CACertOption,
+    CAPathOption,
+    K8sMountPointOption,
+    K8sRoleOption,
+    S3BucketNameOption,
+    S3KeyPrefixOption,
+    SkipVerifyOption,
+    SnapshotFileOption,
+    SnapshotForceRestoreOption,
+    SnapshotNameOption,
+    SnapshotNameRegexOption,
+    TimeoutOption,
+    TokenOption,
+)
+from vaultctl.utils import handle_s3_authentication, handle_vault_authentication, logger
+
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Mapping, Sequence
+
+app = typer.Typer()
+
+
+def select_snapshot(
+    contents: Sequence[Mapping[str, object]],
+    filename_regex: re.Pattern | None,
+) -> str:
+    if filename_regex:
+        valid_objects = []
+
+        for o in contents:
+            key = o.get("Key")
+            if not isinstance(key, str):
+                continue
+
+            match = filename_regex.match(key)
+            if not match:
+                continue
+
+            ts_str = match.group(1)
+            try:
+                ts = parse_datetime(ts_str)
+                valid_objects.append({"Key": key, "Timestamp": ts})
+            except ValueError:
+                continue
+
+        if not valid_objects:
+            msg = "No valid snapshots found matching the filename regex with parseable timestamp"
+            raise ValueError(
+                msg,
+            )
+
+        latest_obj = max(valid_objects, key=lambda o: cast("datetime", o["Timestamp"]))
+        return cast("str", latest_obj["Key"])
+
+    valid_objects = [
+        o
+        for o in contents
+        if isinstance(o.get("Key"), str) and isinstance(o.get("LastModified"), datetime)
+    ]
+    if not valid_objects:
+        msg = "No valid snapshots with LastModified found"
+        raise RuntimeError(msg)
+
+    latest_obj = max(valid_objects, key=lambda o: cast("datetime", o["LastModified"]))
+    return cast("str", latest_obj["Key"])
+
+
+@app.command(help="Restore a HashiCorp Vault cluster from an S3 Raft snapshot.")
+def restore_raft_snapshot(  # noqa: C901, PLR0912, PLR0913, PLR0915
+    address: AddressOption,
+    s3_bucket_name: S3BucketNameOption = None,
+    snapshot_file: SnapshotFileOption = None,
+    k8s_role: K8sRoleOption = None,
+    k8s_mount_point: K8sMountPointOption = "kubernetes",
+    filename: SnapshotNameOption = None,
+    filename_regex: SnapshotNameRegexOption = None,
+    aws_profile: AwsProfileOption = None,
+    aws_access_key_id: AwsAccessKeyIdOption = None,
+    aws_secret_access_key: AwsSecretAccessKeyOption = None,
+    aws_endpoint_url: AwsEndpointUrlOption = None,
+    aws_region: AwsRegionOption = "us-east-1",
+    s3_key_prefix: S3KeyPrefixOption = "",
+    token: TokenOption = None,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
+    timeout: TimeoutOption = 30,
+    *,
+    force_restore: SnapshotForceRestoreOption = False,
+    skip_verify: SkipVerifyOption = False,
+) -> None:
+    if not s3_bucket_name and not snapshot_file:
+        msg = "Either --s3-bucket-name or --snapshot-file is required"
+        raise typer.BadParameter(msg)
+
+    vault_client = handle_vault_authentication(
+        hvac.Client(
+            url=address,
+            timeout=timeout,
+            verify=(
+                str(ca_cert)
+                if ca_cert
+                else str(ca_path)
+                if ca_path
+                else (not skip_verify)
+            ),
+        ),
+        token=token,
+        k8s_role=k8s_role,
+        k8s_mount_point=k8s_mount_point,
+    )
+
+    if vault_client.sys.is_sealed():
+        logger.error("Vault is sealed. Cannot proceed.")
+        raise typer.Exit(code=1)
+
+    if snapshot_file:
+        logger.info("Reading snapshot from %s...", snapshot_file)
+        snapshot_data = Path(snapshot_file).read_bytes()
+    else:
+        s3_bucket_name = cast("str", s3_bucket_name)
+        s3_client = handle_s3_authentication(
+            bucket_name=s3_bucket_name,
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            aws_region=aws_region,
+            aws_profile=aws_profile,
+            endpoint_url=aws_endpoint_url,
+        )
+
+        if filename:
+            s3_key = f"{s3_key_prefix}{filename}"
+            logger.info("Using snapshot: %s", s3_key)
+        else:
+            logger.info("Selecting latest snapshot from S3...")
+
+            try:
+                list_response = s3_client.list_objects_v2(
+                    Bucket=s3_bucket_name,
+                    Prefix=s3_key_prefix,
+                )
+            except botocore.exceptions.ClientError:
+                logger.exception("Listing S3 bucket contents")
+                raise typer.Exit(1) from None
+
+            if list_response.get("KeyCount", 0) == 0:
+                logger.error(
+                    "No snapshots found in bucket '%s' with prefix '%s'.",
+                    s3_bucket_name,
+                    s3_key_prefix,
+                )
+                raise typer.Exit(1)
+
+            contents = list_response.get("Contents", [])
+            try:
+                s3_key = select_snapshot(contents, filename_regex)
+            except (ValueError, RuntimeError):
+                logger.exception("Selecting snapshot")
+                raise typer.Exit(1) from None
+
+            logger.info("Selected snapshot: %s", s3_key)
+
+        logger.info("Downloading snapshot from S3: %s...", s3_key)
+
+        try:
+            download_response = s3_client.get_object(Bucket=s3_bucket_name, Key=s3_key)
+            snapshot_data = download_response["Body"].read()
+        except botocore.exceptions.ClientError:
+            logger.exception("Downloading snapshot")
+            raise typer.Exit(1) from None
+
+        logger.info("Snapshot downloaded.")
+
+    raft = Raft(adapter=vault_client.adapter)
+
+    if force_restore:
+        logger.warning("Restoring snapshot with force...")
+        try:
+            raft.force_restore_raft_snapshot(snapshot_data)
+        except (VaultError, InvalidRequest):
+            logger.exception("Restoring snapshot")
+            raise typer.Exit(1) from None
+    else:
+        logger.info("Restoring snapshot...")
+        try:
+            raft.restore_raft_snapshot(snapshot_data)
+        except (VaultError, InvalidRequest):
+            logger.exception("Restoring snapshot")
+            raise typer.Exit(1) from None
+
+    logger.info("Snapshot restored.")
+    logger.info("Restore completed")

vaultctl/main.py

@@ -0,0 +1,21 @@
+import typer
+
+from vaultctl.commands.backup_raft_snapshot import app as backup_raft_snapshot
+from vaultctl.commands.bootstrap import app as bootstrap
+from vaultctl.commands.login import app as login
+from vaultctl.commands.pki.rotate_issuing import app as pki
+from vaultctl.commands.restore_raft_snapshot import app as restore_raft_snapshot
+from vaultctl.version import app as version
+
+app = typer.Typer(no_args_is_help=True)
+
+app.add_typer(version)
+app.add_typer(bootstrap)
+app.add_typer(restore_raft_snapshot)
+app.add_typer(backup_raft_snapshot)
+app.add_typer(login)
+app.add_typer(pki)
+
+
+if __name__ == "__main__":
+    app()

vaultctl/options.py

@@ -0,0 +1,200 @@
+import re
+from pathlib import Path
+from typing import Annotated
+
+from typer import Option
+
+from .utils import parse_regex, validate_address, validate_s3_key_prefix
+
+AwsEndpointUrlOption = Annotated[
+    str | None,
+    Option(
+        envvar="AWS_ENDPOINT_URL",
+        help="Custom AWS endpoint URL (e.g., for MinIO or Cloudflare R2).",
+    ),
+]
+
+AwsAccessKeyIdOption = Annotated[
+    str | None,
+    Option(envvar="AWS_ACCESS_KEY_ID", help="AWS Access Key ID."),
+]
+
+AwsSecretAccessKeyOption = Annotated[
+    str | None,
+    Option(
+        envvar="AWS_SECRET_ACCESS_KEY",
+        help="AWS Secret Access Key.",
+    ),
+]
+
+AwsProfileOption = Annotated[
+    str | None,
+    Option(envvar="AWS_PROFILE", help="AWS CLI profile name to use."),
+]
+
+AwsRegionOption = Annotated[
+    str,
+    Option(envvar="AWS_REGION", help="AWS Region (e.g., us-east-1)."),
+]
+
+S3BucketNameOption = Annotated[
+    str | None,
+    Option(
+        envvar="S3_BUCKET_NAME",
+        help="Storage bucket where snapshots are stored",
+    ),
+]
+
+S3KeyPrefixOption = Annotated[
+    str,
+    Option(
+        callback=validate_s3_key_prefix,
+    ),
+]
+
+AddressOption = Annotated[
+    str,
+    Option(
+        callback=validate_address,
+        default_factory=lambda: "https://127.0.0.1:8200",
+        envvar="VAULT_ADDR",
+        show_envvar=False,
+        help="Address of the Vault server. The default is https://127.0.0.1:8200. This can also be specified via the VAULT_ADDR environment variable.",
+    ),
+]
+
+TokenOption = Annotated[
+    str | None,
+    Option(
+        envvar="VAULT_TOKEN",
+        show_envvar=False,
+        help=(
+            "Vault token used to authenticate with the Vault server. "
+            "This can also be specified via the VAULT_TOKEN environment variable."
+        ),
+    ),
+]
+
+CACertOption = Annotated[
+    Path | None,
+    Option(
+        envvar="VAULT_CACERT",
+        show_envvar=False,
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        writable=False,
+        resolve_path=True,
+        path_type=str,
+        help=(
+            "Path on the local disk to a single PEM-encoded CA certificate to verify the Vault server's SSL certificate. "
+            "This takes precedence over -ca-path. This can also be specified via the VAULT_CACERT environment variable."
+        ),
+    ),
+]
+
+CAPathOption = Annotated[
+    Path | None,
+    Option(
+        envvar="VAULT_CAPATH",
+        show_envvar=False,
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        writable=False,
+        resolve_path=True,
+        path_type=str,
+        help=(
+            "Path on the local disk to a directory of PEM-encoded CA certificates to verify the Vault server's SSL certificate. "
+            "This can also be specified via the VAULT_CAPATH environment variable."
+        ),
+    ),
+]
+
+SkipVerifyOption = Annotated[
+    bool,
+    Option(
+        show_envvar=False,
+        envvar="VAULT_SKIP_VERIFY",
+        help=(
+            "Disable verification of TLS certificates. Using this option is highly discouraged "
+            "as it decreases the security of data transmissions to and from the Vault server. "
+            "The default is false. This can also be specified via the VAULT_SKIP_VERIFY environment variable."
+        ),
+    ),
+]
+
+K8sRoleOption = Annotated[
+    str | None,
+    Option(envvar="VAULT_K8S_ROLE", help="Vault K8s role name."),
+]
+
+K8sMountPointOption = Annotated[
+    str,
+    Option(envvar="VAULT_K8S_MOUNT_POINT", help="Vault K8s auth backend mount path."),
+]
+
+SnapshotNameOption = Annotated[
+    str | None,
+    Option(
+        help="Name of the Vault snapshot to restore.",
+    ),
+]
+
+SnapshotNameRegexOption = Annotated[
+    re.Pattern | None,
+    Option(
+        parser=parse_regex,
+        help="Regex pattern to match Vault snapshot names.",
+    ),
+]
+
+SnapshotForceRestoreOption = Annotated[
+    bool,
+    Option(
+        help=(
+            "Force snapshot restore when the unseal keys or auto-unseal configuration "
+            "are inconsistent with the snapshot, such as when restoring data from "
+            "a different Vault cluster."
+        ),
+    ),
+]
+
+TimeoutOption = Annotated[
+    int,
+    Option(
+        "--timeout",
+        "-t",
+        help="HTTP request timeout in seconds for Vault API calls.",
+    ),
+]
+
+OutputFileOption = Annotated[
+    Path | None,
+    Option(
+        "--output-file",
+        "-o",
+        help="Path to write the snapshot to locally. If a directory, a timestamped filename is generated.",
+        dir_okay=True,
+        writable=True,
+        resolve_path=True,
+        path_type=str,
+    ),
+]
+
+SnapshotFileOption = Annotated[
+    Path | None,
+    Option(
+        "--snapshot-file",
+        "-f",
+        help="Path to a local snapshot file to restore.",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        path_type=str,
+    ),
+]

vaultctl/utils.py

@@ -0,0 +1,169 @@
+import logging
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+import boto3
+import botocore.exceptions
+import typer
+import validators
+from hvac.exceptions import InvalidRequest, VaultError
+
+if TYPE_CHECKING:
+    import hvac
+    from mypy_boto3_s3 import S3Client
+
+
+def _setup_logger() -> logging.Logger:
+    logger = logging.getLogger("vaultctl")
+    logger.setLevel(logging.INFO)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(
+            logging.Formatter("%(asctime)s %(levelname)s %(message)s"),
+        )
+        logger.addHandler(handler)
+    return logger
+
+
+logger = _setup_logger()
+
+
+def parse_regex(value: str) -> re.Pattern:
+    """Parse and validate a regex pattern."""
+    try:
+        return re.compile(value)
+    except re.error as e:
+        msg = f"Invalid regex: {e}"
+        raise typer.BadParameter(msg) from e
+
+
+def validate_s3_key_prefix(
+    value: str,
+) -> str:
+    """Validate S3 key prefix format."""
+    if not value:
+        return ""
+    if value.startswith("/"):
+        msg = "S3 key prefix must not start with '/'. Example: backups/2026/"
+        raise typer.BadParameter(
+            msg,
+        )
+
+    pattern = re.compile(r"^[A-Za-z0-9/_\-.]+$")
+    if not pattern.match(value):
+        msg = (
+            "S3 key prefix contains invalid characters. "
+            "Allowed: letters, numbers, '/', '-', '_', '.'"
+        )
+        raise typer.BadParameter(
+            msg,
+        )
+
+    if not value.endswith("/"):
+        value = value + "/"
+
+    return value
+
+
+def validate_address(
+    ctx: typer.Context,  # noqa: ARG001
+    param: object,  # noqa: ARG001
+    value: str,
+) -> str:
+    if value == "https://127.0.0.1:8200":
+        logger.warning(
+            "VAULT_ADDR and --address unset. Defaulting to https://127.0.0.1:8200.",
+        )
+    elif not validators.url(value):
+        msg = f"Invalid Vault address URL: {value!r}"
+        raise typer.BadParameter(msg) from None
+    return value
+
+
+def handle_vault_authentication(
+    client: hvac.Client,
+    token: str | None,
+    k8s_role: str | None = None,
+    k8s_mount_point: str = "kubernetes",
+    k8s_token_path: Path = Path("/var/run/secrets/kubernetes.io/serviceaccount/token"),
+) -> hvac.Client:
+    token_filepath = Path.home() / ".vault-token"
+
+    if token:
+        client.token = token
+        return client
+
+    if token_filepath.exists() and (saved_token := token_filepath.read_text().strip()):
+        client.token = saved_token
+        return client
+
+    if k8s_role:
+        logger.info("Attempting Kubernetes Auth for role: %s...", k8s_role)
+
+        if not k8s_token_path.exists():
+            logger.error(
+                "K8s token file not found at %s.",
+                k8s_token_path,
+            )
+            raise typer.Exit(code=1)
+
+        jwt = k8s_token_path.read_text().strip()
+
+        try:
+            client.auth.kubernetes.login(
+                role=k8s_role,
+                jwt=jwt,
+                mount_point=k8s_mount_point,
+            )
+        except InvalidRequest, VaultError:
+            logger.exception("Kubernetes Auth Failed")
+            raise typer.Exit(code=1) from None
+        else:
+            return client
+
+    logger.error("Vault client authentication failed.")
+    raise typer.Exit(code=1)
+
+
+def handle_s3_authentication(  # noqa: PLR0913
+    bucket_name: str,
+    *,
+    aws_access_key_id: str | None = None,
+    aws_secret_access_key: str | None = None,
+    aws_session_token: str | None = None,
+    aws_region: str | None = None,
+    aws_profile: str | None = None,
+    endpoint_url: str | None = None,
+) -> S3Client:
+    logger.info("Initializing S3 client...")
+
+    s3_client: S3Client | None = None
+
+    session = boto3.Session(
+        aws_access_key_id=aws_access_key_id,
+        aws_secret_access_key=aws_secret_access_key,
+        aws_session_token=aws_session_token,
+        region_name=aws_region,
+        profile_name=aws_profile,
+    )
+    s3_client = cast(
+        "S3Client",
+        session.client("s3", endpoint_url=endpoint_url),
+    )
+
+    try:
+        s3_client.head_bucket(Bucket=bucket_name)
+    except botocore.exceptions.ClientError as e:
+        msg = e.response.get("Error", {}).get("Message", "Unknown S3 Error")
+        logger.exception("S3 Head Bucket failed: %s", msg)
+        raise typer.Exit(code=1) from None
+    except (
+        botocore.exceptions.NoCredentialsError,
+        botocore.exceptions.PartialCredentialsError,
+    ):
+        logger.exception("S3 authentication failed")
+        raise typer.Exit(code=1) from None
+
+    logger.info("S3 client initialized.")
+    return s3_client

vaultctl/version.py

@@ -0,0 +1,8 @@
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+def version() -> None:
+    print("vaultctl 0.1.0")  # noqa: T201

vaultctl-0.1.0.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: vaultctl
+Version: 0.1.0
+Summary: vaultctl is a command-line interface (CLI) tool designed to facilitate operations with HashiCorp Vault.
+Author-email: d4rkfella <georgi.panov@darkfellanetwork.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.14
+Requires-Dist: boto3==1.43.27
+Requires-Dist: botocore[crt]
+Requires-Dist: cryptography==48.0.1
+Requires-Dist: hvac==2.4
+Requires-Dist: python-dateutil==2.9.0
+Requires-Dist: typer==0.26.7
+Requires-Dist: validators==0.35.0
+Description-Content-Type: text/markdown
+
+vaultctl is a command-line interface (CLI) tool designed to facilitate operations with HashiCorp Vault.

vaultctl-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+vaultctl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vaultctl/main.py,sha256=AvjD-_aAVKZnJL47JTQHQ0TdzHMXdx2X43L-k7yYU10,626
+vaultctl/options.py,sha256=qro57yji4t405wvqrEhnru5KWPVxwI117Ijuq8qhWOM,4957
+vaultctl/utils.py,sha256=rzpSdSRVvInXrT6fQcR915lfqLZgD63-otqlAbqv5u0,4666
+vaultctl/version.py,sha256=p8yxo-e4AKNsdRHguAP-EbLAoiTy-v0Lm8QpFPqs8G4,116
+vaultctl/commands/__init__.py,sha256=ei3gcSupb8CrtiehtC1WQUlHPeiqS48Ld3IuXHkjACY,500
+vaultctl/commands/backup_raft_snapshot.py,sha256=ux2HF7daEg6FQGY2f0fqwy_JMnPY23Ih8X5WQDjUIeQ,7381
+vaultctl/commands/bootstrap.py,sha256=9AvZeYfT5itKDEd-ASYZr-n_Pq6-zGAAX-coMfCnZys,4153
+vaultctl/commands/login.py,sha256=yA2mkGnp2FBJw3duYLr_fPVQUWr-SRPQaeb-KoSAQ7k,3902
+vaultctl/commands/restore_raft_snapshot.py,sha256=AO29XiQ5MeEyRST6MNIrmTZz14fkgy8s_6meMCheEJs,6811
+vaultctl/commands/pki/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vaultctl/commands/pki/rotate_issuing.py,sha256=DOFjmbGLO-ijfXIOpHRHQo83S0UZa078sT6RYNghuL8,4736
+vaultctl-0.1.0.dist-info/METADATA,sha256=sQnnKFME6ljmAJfUVqcswj3UvLlE6XCiLYkrGvNc3os,655
+vaultctl-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vaultctl-0.1.0.dist-info/entry_points.txt,sha256=Ut-6BJDScK48S6e5KxZmhqOwFs6xUNXBa9dvrjlYx7c,47
+vaultctl-0.1.0.dist-info/licenses/LICENSE,sha256=di8AMq7X7mboEdzQil3E3zagCDzZbz00D30zzXmO0ZM,1069
+vaultctl-0.1.0.dist-info/RECORD,,

vaultctl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

vaultctl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vaultctl = vaultctl.main:app

vaultctl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Georgi Panov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.