vaultctl 0.1.0__tar.gz

vaultctl-0.1.0/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,14 @@
+{
+  "features": {
+    "ghcr.io/devcontainers-extra/features/ruff:2.0.0": {
+      "version": "2.0.0",
+      "resolved": "ghcr.io/devcontainers-extra/features/ruff@sha256:80f1d8ff0fbd84fffbc9383ff11cc54524898f8bbc820cae642dff4902575117",
+      "integrity": "sha256:80f1d8ff0fbd84fffbc9383ff11cc54524898f8bbc820cae642dff4902575117"
+    },
+    "ghcr.io/devcontainers-extra/features/uv:1.0.2": {
+      "version": "1.0.2",
+      "resolved": "ghcr.io/devcontainers-extra/features/uv@sha256:1ac5b9f17a9e9e745933d0ac2ecf758e06ed3da4423cd22c94cce4d482fd2dd8",
+      "integrity": "sha256:1ac5b9f17a9e9e745933d0ac2ecf758e06ed3da4423cd22c94cce4d482fd2dd8"
+    }
+  }
+}

vaultctl-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+	"name": "vaultctl devcontainer",
+	"image": "mcr.microsoft.com/devcontainers/python:3-3.14",
+    "postCreateCommand": "uv sync",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python",
+				"ms-python.vscode-pylance",
+				"charliermarsh.ruff",
+				"the0807.uv-toolkit"
+			],
+			"settings": {
+				"python.defaultInterpreterPath": "/workspaces/vaultctl/.venv/bin/python",
+				"[python]": {
+					"editor.defaultFormatter": "charliermarsh.ruff",
+					"editor.formatOnSave": true
+				},
+				"ruff.path": ["/usr/local/bin/ruff"]
+			}
+		}
+	},
+	"features": {
+		"ghcr.io/devcontainers-extra/features/uv:1.0.2": {},
+		"ghcr.io/devcontainers-extra/features/ruff:2.0.0": { "version": "0.15.16"}
+	}
+}

vaultctl-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,121 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+  attestations: write
+  artifact-metadata: write
+
+jobs:
+  docker:
+    runs-on: ubuntu-24.04
+    env:
+      REGISTRY: ghcr.io
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Get project name and version from pyproject.toml
+        id: meta
+        run: |
+          python3 <<'PY'
+          import tomllib, pathlib
+          p = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
+          print(f"version={p['version']}")
+          print(f"name={p['name']}")
+          PY
+        shell: bash
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+
+      - name: Set up Cosign
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build CLI package
+        run: |
+          rm -rf dist/ build/ *.egg-info
+          uv build
+
+      - name: Publish CLI to PyPI
+        run: |
+          uv publish
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        with:
+          tag_name: v${{ steps.meta.outputs.version }}
+          name: v${{ steps.meta.outputs.version }}
+          generate_release_notes: true
+          files: |
+            dist/*
+
+      - name: Build and Push Docker Image
+        id: build-and-push
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          provenance: false
+          build-args: |
+            CLI_VERSION=${{ steps.meta.outputs.version }}
+            VENDOR=${{ github.repository_owner }}
+          labels: |
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.vendor=${{ github.repository_owner }}
+            org.opencontainers.image.url=https://ghcr.io/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}
+          tags: |
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}:latest
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}:${{ steps.meta.outputs.version }}
+
+      - name: Sign Image with Cosign
+        run: |
+          cosign sign --yes \
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}@${{ steps.build-and-push.outputs.digest }}
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}
+          subject-digest: ${{ steps.build-and-push.outputs.digest }}
+          push-to-registry: true
+
+      - name: Generate SBOM
+        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+        with:
+          image: ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}@${{ steps.build-and-push.outputs.digest }}
+          format: spdx-json
+          output-file: sbom.spdx.json
+
+      - name: Attest SBOM
+        uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ steps.meta.outputs.name }}
+          subject-digest: ${{ steps.build-and-push.outputs.digest }}
+          sbom-path: sbom.spdx.json
+          push-to-registry: true

vaultctl-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+dist
+.*_cache

vaultctl-0.1.0/.renovaterc.json5

@@ -0,0 +1,23 @@
+{
+  $schema: 'https://docs.renovatebot.com/renovate-schema.json',
+  extends: [
+    'config:recommended',
+    'docker:enableMajor',
+    'customManagers:dockerfileVersions',
+    'helpers:pinGitHubActionDigests',
+    ':disableRateLimiting',
+    ':dependencyDashboard',
+    ':semanticCommits',
+    ':timezone(Europe/Sofia)',
+  ],
+  dependencyDashboardTitle: 'Renovate Dashboard 🤖',
+  suppressNotifications: [
+    'prEditedNotification',
+    'prIgnoreNotification',
+  ],
+  pip_requirements: {
+    enabled: true,
+    managerFilePatterns: ["(^|/)pyproject([-.]\\w+)?\\.toml$"],
+  },
+}
+

vaultctl-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.14-slim@sha256:9b81fe9acff79e61affb44aaf3b6ff234392e8ca477cb86c9f7fd11732ce9b6a
+
+RUN \
+    groupadd -g 65532 nonroot \
+    && \
+    useradd -r -u 65532 -g 65532 -m nonroot
+
+
+COPY dist/*.whl /tmp/
+RUN \
+    pip install --no-cache-dir /tmp/*.whl \
+    && \
+    rm -f /tmp/*.whl
+
+USER nonroot
+
+ENTRYPOINT ["vaultctl"]

vaultctl-0.1.0/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.

vaultctl-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1 @@
+vaultctl is a command-line interface (CLI) tool designed to facilitate operations with HashiCorp Vault.

vaultctl-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "vaultctl"
+version = "0.1.0"
+description = "vaultctl is a command-line interface (CLI) tool designed to facilitate operations with HashiCorp Vault."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "d4rkfella", email = "georgi.panov@darkfellanetwork.com" }
+]
+requires-python = ">=3.14,<4.0"
+dependencies = [
+    "typer==0.26.7",
+    "validators==0.35.0",
+    "hvac==2.4",
+    "cryptography==48.0.1",
+    "python-dateutil==2.9.0",
+    "boto3==1.43.27",
+    "botocore[crt]",
+]
+
+[project.scripts]
+vaultctl = "vaultctl.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vaultctl"]
+
+[dependency-groups]
+dev = [
+    "types-hvac==2.4.0.20260610",
+    "mypy-boto3-s3==1.43.14",
+]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "E501",
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107",
+    "D211",
+    "D213",
+    "D203",
+]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = [
+    "typing.Annotated", 
+    "typing_extensions.Annotated"
+]
+
+runtime-evaluated-decorators = [
+    "typer.Typer.command",
+    "typer.Typer.callback"
+]

vaultctl-0.1.0/src/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-0.1.0/src/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")