Files
codex 710c483f34
CI / tests-and-images (pull_request) Successful in 2m15s
Runner smoke test / runner-smoke (pull_request) Successful in 3s
Harden external release preparation workflow
2026-11-03 09:38:37 +03:00

316 lines
16 KiB
Python

"""Verify a Gitea release and its exact uploaded descriptor through gitea-api."""
from __future__ import annotations
import base64
import hashlib
import json
import os
import re
import resource
import signal
import stat
import subprocess
import tempfile
import zipfile
from pathlib import Path, PurePosixPath
from urllib.parse import urlencode
from release_handoff import descriptor_request, latest_main_sha, validate_source
from validate_release import read_json, unique_object, validate_manifest
REPOSITORY = "admin/akyldash"
RELEASE_WORKFLOW = ".gitea/workflows/release-images.yaml"
CI_WORKFLOW = ".gitea/workflows/ci.yaml"
MAX_DESCRIPTOR_BYTES = 1024 * 1024
MAX_API_RESPONSE_BYTES = 1024 * 1024
MAX_API_DOWNLOAD_BYTES = 10 * 1024 * 1024
MAX_CANDIDATE_RELEASE_RUNS = 10
API_TIMEOUT_SECONDS = 15
RUNTIME_FILES = (
"deploy/production/compose.yaml",
"deploy/production/Caddyfile",
"infra/deploy/release-policy.json",
)
MAX_RUNTIME_FILE_BYTES = 256 * 1024
def run_api_helper(command: list[str], *, env: dict | None, timeout: int,
max_stdout_bytes: int, max_file_bytes: int) -> bytes:
def limit_files() -> None:
_soft, hard = resource.getrlimit(resource.RLIMIT_FSIZE)
limit = max_file_bytes + 1 if hard == resource.RLIM_INFINITY else min(max_file_bytes + 1, hard)
resource.setrlimit(resource.RLIMIT_FSIZE, (limit, hard))
with tempfile.TemporaryFile() as output:
process = subprocess.Popen(
command, stdout=output, stderr=subprocess.DEVNULL, env=env,
start_new_session=True, preexec_fn=limit_files,
)
try:
return_code = process.wait(timeout=timeout)
except subprocess.TimeoutExpired as error:
try:
os.killpg(process.pid, signal.SIGTERM)
except ProcessLookupError:
pass
try:
process.wait(timeout=2)
except subprocess.TimeoutExpired:
pass
try:
os.killpg(process.pid, signal.SIGKILL)
except ProcessLookupError:
pass
process.wait()
raise ValueError("Gitea helper request timed out") from error
if return_code:
raise ValueError("Gitea helper request failed")
output.seek(0, os.SEEK_END)
if output.tell() > max_stdout_bytes:
raise ValueError("Gitea helper response exceeds its size limit")
output.seek(0)
return output.read(max_stdout_bytes + 1)
def api_json(path: str, *, helper: str = "gitea-api", env: dict | None = None) -> dict:
try:
response = run_api_helper(
[helper, "GET", path], env=env, timeout=API_TIMEOUT_SECONDS,
max_stdout_bytes=MAX_API_RESPONSE_BYTES, max_file_bytes=MAX_API_RESPONSE_BYTES,
)
except (OSError, subprocess.SubprocessError) as error:
raise ValueError("Gitea API request failed") from error
if len(response) > MAX_API_RESPONSE_BYTES:
raise ValueError("Gitea helper response exceeds its size limit")
try:
value = json.loads(response.decode("utf-8"), object_pairs_hook=unique_object)
except (UnicodeError, json.JSONDecodeError) as error:
raise ValueError("Gitea API response is invalid JSON") from error
if not isinstance(value, dict):
raise ValueError("Gitea API returned a non-object response")
return value
def repository_file(path: str, commit: str, *, api=api_json) -> bytes:
"""Fetch one small, pinned repository file and verify Gitea's git blob identity."""
if not re.fullmatch(r"[0-9a-f]{40}", commit) or path not in RUNTIME_FILES:
raise ValueError("runtime file request is not allowlisted or commit-pinned")
query = urlencode({"ref": commit})
value = api(f"/repos/{REPOSITORY}/contents/{path}?{query}")
if (value.get("type") != "file" or value.get("path") != path
or value.get("encoding") != "base64"):
raise ValueError("Gitea runtime file metadata is invalid")
encoded, blob_sha, size = value.get("content"), value.get("sha"), value.get("size")
if (not isinstance(encoded, str) or not isinstance(blob_sha, str)
or not re.fullmatch(r"[0-9a-f]{40}", blob_sha)
or isinstance(size, bool) or not isinstance(size, int)
or size < 0 or size > MAX_RUNTIME_FILE_BYTES):
raise ValueError("Gitea runtime file exceeds its limit or has invalid metadata")
try:
content = base64.b64decode(encoded, validate=True)
except (ValueError, base64.binascii.Error) as error:
raise ValueError("Gitea runtime file content is invalid base64") from error
git_blob_sha = hashlib.sha1(b"blob " + str(len(content)).encode("ascii") + b"\0" + content).hexdigest()
if len(content) != size or git_blob_sha != blob_sha:
raise ValueError("Gitea runtime file content does not match its pinned git blob")
return content
def runtime_compatibility_reason(commit: str, *, checkout: Path, policy_file: Path,
api=api_json) -> str | None:
"""Require the bootstrap host's fixed runtime/configuration to match target source."""
for relative in RUNTIME_FILES:
local_path = policy_file if relative == "infra/deploy/release-policy.json" else checkout / relative
try:
info = local_path.lstat()
if not stat.S_ISREG(info.st_mode):
raise ValueError(f"protected runtime file is not a regular file: {relative}")
local_content = local_path.read_bytes()
except OSError as error:
raise ValueError(f"protected runtime file is unavailable: {relative}") from error
remote_content = repository_file(relative, commit, api=api)
if local_content != remote_content:
return "release_policy_changed" if relative.endswith("release-policy.json") else "runtime_config_changed"
return None
def require_runtime_compatibility(commit: str, *, checkout: Path, policy_file: Path,
api=api_json) -> None:
reason = runtime_compatibility_reason(
commit, checkout=checkout, policy_file=policy_file, api=api,
)
if reason is not None:
raise ValueError(f"host {reason.replace('_', ' ')}; reviewed bootstrap update is required")
def latest_release_request(*, current_main: str, api=api_json,
checkout: Path | None = None) -> dict | None:
if not re.fullmatch(r"[0-9a-f]{40}", current_main):
raise ValueError("current main commit is invalid")
query = urlencode({
"event": "workflow_run", "branch": "main", "status": "success",
"head_sha": current_main, "page": 1, "limit": MAX_CANDIDATE_RELEASE_RUNS,
})
runs_response = api(
f"/repos/{REPOSITORY}/actions/workflows/{Path(RELEASE_WORKFLOW).name}/runs?{query}"
)
runs = runs_response.get("workflow_runs")
total = runs_response.get("total_count")
if type(total) is not int or total < 0 or not isinstance(runs, list):
raise ValueError("Gitea release-run listing is invalid")
if total > MAX_CANDIDATE_RELEASE_RUNS or len(runs) != total:
raise ValueError("Gitea release-run listing is incomplete")
if not runs:
return None
run_ids = []
for run in runs:
if not isinstance(run, dict):
raise ValueError("Gitea release-run listing contains an invalid entry")
run_id = run.get("id")
if (isinstance(run_id, bool) or not isinstance(run_id, (int, str))
or not str(run_id).isdigit() or len(str(run_id)) > 20):
raise ValueError("Gitea release-run listing contains an invalid run ID")
head_sha = run.get("head_sha")
if head_sha is not None and head_sha != current_main:
raise ValueError("Gitea release-run listing does not match current main")
run_ids.append(str(run_id))
run_id = max(run_ids, key=int)
verify_run(run_id, stage="handoff", commit=current_main, api=api,
current_main=current_main, checkout=checkout)
metadata = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}/artifacts")
return descriptor_request(metadata, run_id=run_id, head_sha=current_main)
def ensure_private_scratch(path: Path) -> None:
path.mkdir(mode=0o700, parents=True, exist_ok=True)
if path.is_symlink() or path.stat().st_uid != 0 or path.stat().st_mode & 0o077:
raise ValueError("artifact scratch directory must be a private root-owned directory")
def verify_run(run_id: str, *, stage: str, commit: str, api=api_json, current_main: str | None = None,
checkout: Path | None = None) -> dict:
if not run_id.isdigit() or not re.fullmatch(r"[0-9a-f]{40}", commit):
raise ValueError("Gitea run identity is invalid")
run = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}")
if not isinstance(run, dict) or str(run.get("id")) != run_id:
raise ValueError("Gitea returned a different workflow run")
if run.get("status") not in {"completed", "success"} or run.get("conclusion") != "success":
raise ValueError("workflow run is not successful")
workflow_id = run.get("workflow_id")
if not isinstance(workflow_id, (int, str)) or not str(workflow_id):
raise ValueError("workflow run has no workflow identity")
workflow = api(f"/repos/{REPOSITORY}/actions/workflows/{workflow_id}")
expected_workflow, path, event = (
("CI", CI_WORKFLOW, "push") if stage == "ci" else
("Release production images", RELEASE_WORKFLOW, "workflow_run")
)
if (workflow.get("name") != expected_workflow or workflow.get("path") != path
or str(workflow.get("id")) != str(workflow_id)):
raise ValueError("workflow ID does not resolve to the approved workflow name and path")
if run.get("name") not in {None, expected_workflow}:
raise ValueError("workflow run name is not approved")
if run.get("head_sha") != commit:
raise ValueError("workflow run commit does not match the release request")
branch = run.get("head_branch")
if branch != "main" or run.get("event") != event:
raise ValueError("workflow run is not the approved main event")
validate_source(
workflow=expected_workflow, workflow_path=f"{Path(path).name}@refs/heads/main", event=event,
conclusion="success", branch=branch, run_id=run_id, head_sha=commit,
repository=REPOSITORY, stage="release" if stage == "ci" else "handoff",
current_main=current_main or latest_main_sha(checkout),
)
return run
def validate_artifact_zip(path: Path, *, descriptor_sha256: str, release_run_id: str,
ci_run_id: str | None, commit: str, policy: object) -> tuple[dict, bytes]:
if not re.fullmatch(r"[0-9a-f]{64}", descriptor_sha256):
raise ValueError("requested descriptor digest is invalid")
try:
with zipfile.ZipFile(path) as archive:
members = archive.infolist()
names = [member.filename for member in members]
expected = {"release-manifest.json", "release-manifest.json.sha256"}
if len(names) != 2 or set(names) != expected:
raise ValueError("release artifact must contain exactly the manifest and checksum files")
payloads = {}
for member in members:
name = PurePosixPath(member.filename)
mode = member.external_attr >> 16
kind = stat.S_IFMT(mode)
if (member.is_dir() or name.is_absolute() or len(name.parts) != 1
or name.as_posix() != member.filename
or kind not in {0, stat.S_IFREG}
or member.file_size > MAX_DESCRIPTOR_BYTES
or member.compress_size > MAX_DESCRIPTOR_BYTES):
raise ValueError("release artifact contains an unsafe or oversized member")
with archive.open(member) as stream:
chunks = []
size = 0
while chunk := stream.read(64 * 1024):
size += len(chunk)
if size > MAX_DESCRIPTOR_BYTES:
raise ValueError("release artifact member exceeds its size limit")
chunks.append(chunk)
if size != member.file_size:
raise ValueError("release artifact member size does not match its ZIP metadata")
payloads[member.filename] = b"".join(chunks)
except (OSError, zipfile.BadZipFile, RuntimeError) as error:
raise ValueError(f"release artifact ZIP is invalid: {error}") from error
manifest_bytes = payloads["release-manifest.json"]
if hashlib.sha256(manifest_bytes).hexdigest() != descriptor_sha256:
raise ValueError("release descriptor bytes do not match the requested SHA-256")
checksum = payloads["release-manifest.json.sha256"]
expected_sidecar = f"{descriptor_sha256} release-manifest.json\n".encode("ascii")
if checksum != expected_sidecar:
raise ValueError("release descriptor checksum sidecar is invalid")
try:
manifest = json.loads(manifest_bytes, object_pairs_hook=unique_object)
except (UnicodeError, json.JSONDecodeError) as error:
raise ValueError("release descriptor JSON is invalid") from error
validated = validate_manifest(manifest, policy)
if (validated["run_id"] != release_run_id
or (ci_run_id is not None and validated["source_run_id"] != ci_run_id)
or validated["commit"] != commit):
raise ValueError("release descriptor does not bind the verified CI and release runs")
return validated, manifest_bytes
def fetch_release(request: dict, *, policy: object, helper: str = "gitea-api",
temp_dir: Path = Path("/run/akyldash"), env: dict | None = None,
api=api_json, current_main: str | None = None,
checkout: Path | None = None) -> tuple[dict, bytes]:
run_id, commit, descriptor_sha256 = (
request["run_id"], request["commit"], request["descriptor_sha256"]
)
current_main = current_main or latest_main_sha(checkout)
release_run = verify_run(run_id, stage="handoff", commit=commit, api=api,
current_main=current_main, checkout=checkout)
metadata = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}/artifacts")
tuple_data = descriptor_request(metadata, run_id=run_id, head_sha=commit)
if tuple_data["descriptor_sha256"] != descriptor_sha256:
raise ValueError("requested descriptor digest does not match the Gitea run artifact")
artifact = metadata["artifacts"][0]
artifact_id = artifact.get("id")
if not isinstance(artifact_id, (int, str)) or not str(artifact_id).isdigit():
raise ValueError("release descriptor artifact has no numeric ID")
ensure_private_scratch(temp_dir)
from tempfile import TemporaryDirectory
with TemporaryDirectory(prefix="akyldash-release-", dir=temp_dir) as scratch:
zip_path = Path(scratch) / "artifact.zip"
run_api_helper(
[helper, "DOWNLOAD", f"/repos/{REPOSITORY}/actions/artifacts/{artifact_id}/zip", str(zip_path)],
env=env, timeout=30, max_stdout_bytes=4096, max_file_bytes=MAX_API_DOWNLOAD_BYTES,
)
manifest, manifest_bytes = validate_artifact_zip(
zip_path, descriptor_sha256=tuple_data["descriptor_sha256"], release_run_id=run_id,
ci_run_id=None, commit=commit, policy=policy,
)
source_run_id = manifest["source_run_id"]
verify_run(source_run_id, stage="ci", commit=commit, api=api, current_main=current_main,
checkout=checkout)
return manifest, manifest_bytes