system-design-primer-skill 2.3.0 → 2.4.0
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.
- package/README.md +15 -7
- package/SKILL.md +22 -2
- package/VERSION +1 -1
- package/evals/README.md +1022 -0
- package/evals/system-design-cases.json +414 -0
- package/package.json +3 -2
- package/references/03-data-and-storage.md +8 -2
- package/references/04-caching.md +3 -3
- package/references/05-async-and-messaging.md +4 -0
- package/references/06-distributed-systems.md +2 -2
- package/references/07-reliability-and-resilience.md +7 -3
- package/references/08-api-security-observability.md +4 -0
- package/references/15-failure-analysis.md +4 -0
- package/references/19-agent-security-and-permissions.md +22 -6
- package/references/20-agent-state-and-memory.md +4 -0
- package/references/22-kubernetes-and-container-platforms.md +1 -1
- package/references/24-multi-region-and-disaster-recovery.md +6 -2
- package/references/27-production-observability-and-slo.md +4 -0
- package/references/28-event-streaming-and-kafka-pulsar.md +6 -0
- package/references/32-workflow-orchestration-and-temporal.md +4 -0
- package/references/34-postgresql-internals-and-performance.md +2 -0
- package/references/35-mysql-innodb-and-performance.md +2 -0
- package/references/36-sharding-and-distributed-sql.md +1 -1
- package/references/37-consensus-and-distributed-transactions.md +7 -3
- package/references/40-zero-downtime-database-migrations.md +3 -3
- package/references/48-oauth-oidc-and-passkeys.md +3 -3
- package/references/49-iam-rbac-abac-rebac.md +7 -3
- package/references/51-secrets-kms-pki-and-key-management.md +4 -0
- package/references/52-supply-chain-security-sbom-slsa.md +62 -0
- package/references/54-privacy-engineering-and-data-governance.md +4 -0
- package/references/55-opentelemetry-and-instrumentation.md +4 -0
- package/references/56-distributed-tracing-and-context-propagation.md +4 -0
- package/references/59-capacity-planning-and-performance-modeling.md +8 -4
- package/references/60-chaos-engineering-and-resilience-experiments.md +4 -0
- package/references/61-incident-management-and-postmortems.md +4 -0
- package/references/67-storage-infrastructure-and-storage-systems.md +4 -0
- package/references/68-tcp-quic-and-network-performance.md +1 -1
- package/references/69-task-routing-and-evidence.md +75 -18
- package/scripts/audit_chain.py +36 -0
- package/scripts/compare_reports.py +43 -0
- package/scripts/evaluate.py +475 -0
- package/scripts/evaluation_catalog.py +129 -0
- package/scripts/evaluation_fingerprints.py +20 -0
- package/scripts/evidence_archive.py +79 -0
- package/scripts/evidence_signing.py +98 -0
- package/scripts/evidence_timestamp.py +441 -0
- package/scripts/install.ps1 +2 -2
- package/scripts/install.sh +2 -2
- package/scripts/report_integrity.py +184 -0
- package/scripts/review_consensus.py +77 -0
- package/scripts/review_evidence.py +105 -0
- package/scripts/review_provenance.py +44 -0
- package/scripts/reviewer_calibration.py +215 -0
- package/scripts/rubric_compatibility.py +134 -0
- package/scripts/run_evals.py +130 -0
- package/scripts/run_manifest.py +179 -0
- package/scripts/statistical_analysis.py +308 -0
- package/scripts/tsa_attestation.py +709 -0
- package/scripts/tsa_validation_report.py +627 -0
- package/scripts/validate.py +233 -21
- package/scripts/verify_build_provenance.py +625 -0
- package/scripts/verify_tsa_ocsp.py +962 -0
- package/scripts/verify_tsa_revocation.py +782 -0
- package/scripts/windows_broker_protocol.py +274 -0
- package/scripts/windows_broker_transport.py +141 -0
- package/scripts/windows_broker_win32.py +713 -0
|
@@ -0,0 +1,625 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Verify GitHub-hosted SLSA build provenance for a distribution artifact.
|
|
3
|
+
|
|
4
|
+
Cryptographic bundle, certificate, transparency-log, and trust-root verification
|
|
5
|
+
is delegated to a security-patched GitHub CLI. This wrapper adds a strict
|
|
6
|
+
repository, workflow, source-ref, source-commit, predicate, and subject policy.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import argparse
|
|
11
|
+
import hashlib
|
|
12
|
+
import json
|
|
13
|
+
import os
|
|
14
|
+
import re
|
|
15
|
+
import shutil
|
|
16
|
+
import signal
|
|
17
|
+
import stat
|
|
18
|
+
import subprocess
|
|
19
|
+
import sys
|
|
20
|
+
import tempfile
|
|
21
|
+
import time
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
from typing import Any
|
|
24
|
+
|
|
25
|
+
SHA1_RE = re.compile(r"^[0-9a-f]{40}$")
|
|
26
|
+
REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
|
|
27
|
+
GH_VERSION_RE = re.compile(r"^gh version (\d+)\.(\d+)\.(\d+)(?: \([^()\r\n]+\))?$")
|
|
28
|
+
MIN_GH_VERSION = (2, 102, 0)
|
|
29
|
+
GH_VERSION_TIMEOUT_SECONDS = 30
|
|
30
|
+
GH_VERIFY_TIMEOUT_SECONDS = 300
|
|
31
|
+
GH_VERSION_STDOUT_LIMIT_BYTES = 64 * 1024
|
|
32
|
+
GH_VERIFY_STDOUT_LIMIT_BYTES = 16 * 1024 * 1024
|
|
33
|
+
GH_STDERR_LIMIT_BYTES = 64 * 1024
|
|
34
|
+
GH_STDERR_TAIL_BYTES = 4 * 1024
|
|
35
|
+
PREDICATE_TYPE = "https://slsa.dev/provenance/v1"
|
|
36
|
+
OIDC_ISSUER = "https://token.actions.githubusercontent.com"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _is_valid_git_ref(ref: str) -> bool:
|
|
40
|
+
"""Apply git-check-ref-format rules relevant to an untrusted CLI argument."""
|
|
41
|
+
if not isinstance(ref, str) or not ref.startswith(("refs/heads/", "refs/tags/")):
|
|
42
|
+
return False
|
|
43
|
+
forbidden = (" ", "~", "^", ":", "?", "*", "[", chr(92))
|
|
44
|
+
if any(ord(char) < 32 or ord(char) == 127 or char in forbidden for char in ref):
|
|
45
|
+
return False
|
|
46
|
+
if ref.endswith(("/", ".")) or "//" in ref or ".." in ref or "@{" in ref:
|
|
47
|
+
return False
|
|
48
|
+
components = ref.split("/")
|
|
49
|
+
return all(component and component != "@" and not component.startswith(".") and not component.endswith((".", ".lock")) for component in components)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _require_regular_file(path: Path, label: str) -> None:
|
|
54
|
+
"""Reject symlinks and non-regular filesystem objects at the input boundary."""
|
|
55
|
+
try:
|
|
56
|
+
mode = path.lstat().st_mode
|
|
57
|
+
except OSError as exc:
|
|
58
|
+
raise ValueError(f"{label} must identify an existing regular file") from exc
|
|
59
|
+
if not stat.S_ISREG(mode):
|
|
60
|
+
raise ValueError(f"{label} must identify an existing regular file, not a symlink or special file")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _copy_regular_file_snapshot(source: Path, destination: Path, label: str) -> None:
|
|
64
|
+
"""Copy from one verified file descriptor, rejecting path swaps and observed writes."""
|
|
65
|
+
try:
|
|
66
|
+
before = source.lstat()
|
|
67
|
+
except OSError as exc:
|
|
68
|
+
raise ValueError(f"{label} must identify an existing regular file") from exc
|
|
69
|
+
if not stat.S_ISREG(before.st_mode):
|
|
70
|
+
raise ValueError(f"{label} must identify an existing regular file, not a symlink or special file")
|
|
71
|
+
|
|
72
|
+
flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
|
|
73
|
+
try:
|
|
74
|
+
descriptor = os.open(source, flags)
|
|
75
|
+
except OSError as exc:
|
|
76
|
+
raise ValueError(f"{label} could not be opened as a regular file") from exc
|
|
77
|
+
|
|
78
|
+
try:
|
|
79
|
+
source_stream = os.fdopen(descriptor, "rb")
|
|
80
|
+
except Exception:
|
|
81
|
+
try:
|
|
82
|
+
os.close(descriptor)
|
|
83
|
+
except OSError:
|
|
84
|
+
pass
|
|
85
|
+
raise
|
|
86
|
+
|
|
87
|
+
destination_created = False
|
|
88
|
+
try:
|
|
89
|
+
with source_stream:
|
|
90
|
+
opened = os.fstat(source_stream.fileno())
|
|
91
|
+
if not stat.S_ISREG(opened.st_mode) or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino):
|
|
92
|
+
raise ValueError(f"{label} changed identity while being opened")
|
|
93
|
+
destination_flags = (
|
|
94
|
+
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
|
|
95
|
+
)
|
|
96
|
+
destination_descriptor = os.open(destination, destination_flags, 0o600)
|
|
97
|
+
destination_created = True
|
|
98
|
+
try:
|
|
99
|
+
destination_stream = os.fdopen(destination_descriptor, "wb")
|
|
100
|
+
except Exception:
|
|
101
|
+
try:
|
|
102
|
+
os.close(destination_descriptor)
|
|
103
|
+
except OSError:
|
|
104
|
+
pass
|
|
105
|
+
raise
|
|
106
|
+
with destination_stream:
|
|
107
|
+
shutil.copyfileobj(source_stream, destination_stream)
|
|
108
|
+
after = os.fstat(source_stream.fileno())
|
|
109
|
+
stable_fields = ("st_size", "st_mtime_ns", "st_ctime_ns")
|
|
110
|
+
if any(getattr(opened, field, None) != getattr(after, field, None) for field in stable_fields):
|
|
111
|
+
raise ValueError(f"{label} changed while being snapshotted")
|
|
112
|
+
except Exception:
|
|
113
|
+
if destination_created:
|
|
114
|
+
try:
|
|
115
|
+
destination.unlink()
|
|
116
|
+
except OSError:
|
|
117
|
+
# Preserve the original snapshot failure; the enclosing private
|
|
118
|
+
# TemporaryDirectory remains responsible for final cleanup.
|
|
119
|
+
pass
|
|
120
|
+
raise
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _create_windows_job(process: subprocess.Popen[bytes]):
|
|
125
|
+
"""Assign an already-running CLI to a kill-on-close Job Object.
|
|
126
|
+
|
|
127
|
+
This contains descendants created after assignment, but cannot close the
|
|
128
|
+
startup race between Popen returning and AssignProcessToJobObject. Strict
|
|
129
|
+
containment requires creation-time Job Object association via a native
|
|
130
|
+
STARTUPINFOEX/PROC_THREAD_ATTRIBUTE_JOB_LIST launch path.
|
|
131
|
+
"""
|
|
132
|
+
if os.name != "nt":
|
|
133
|
+
return None
|
|
134
|
+
|
|
135
|
+
import ctypes
|
|
136
|
+
from ctypes import wintypes
|
|
137
|
+
|
|
138
|
+
class BasicLimitInformation(ctypes.Structure):
|
|
139
|
+
_fields_ = [
|
|
140
|
+
("PerProcessUserTimeLimit", ctypes.c_longlong),
|
|
141
|
+
("PerJobUserTimeLimit", ctypes.c_longlong),
|
|
142
|
+
("LimitFlags", wintypes.DWORD),
|
|
143
|
+
("MinimumWorkingSetSize", ctypes.c_size_t),
|
|
144
|
+
("MaximumWorkingSetSize", ctypes.c_size_t),
|
|
145
|
+
("ActiveProcessLimit", wintypes.DWORD),
|
|
146
|
+
("Affinity", ctypes.c_size_t),
|
|
147
|
+
("PriorityClass", wintypes.DWORD),
|
|
148
|
+
("SchedulingClass", wintypes.DWORD),
|
|
149
|
+
]
|
|
150
|
+
|
|
151
|
+
class IoCounters(ctypes.Structure):
|
|
152
|
+
_fields_ = [
|
|
153
|
+
("ReadOperationCount", ctypes.c_ulonglong),
|
|
154
|
+
("WriteOperationCount", ctypes.c_ulonglong),
|
|
155
|
+
("OtherOperationCount", ctypes.c_ulonglong),
|
|
156
|
+
("ReadTransferCount", ctypes.c_ulonglong),
|
|
157
|
+
("WriteTransferCount", ctypes.c_ulonglong),
|
|
158
|
+
("OtherTransferCount", ctypes.c_ulonglong),
|
|
159
|
+
]
|
|
160
|
+
|
|
161
|
+
class ExtendedLimitInformation(ctypes.Structure):
|
|
162
|
+
_fields_ = [
|
|
163
|
+
("BasicLimitInformation", BasicLimitInformation),
|
|
164
|
+
("IoInfo", IoCounters),
|
|
165
|
+
("ProcessMemoryLimit", ctypes.c_size_t),
|
|
166
|
+
("JobMemoryLimit", ctypes.c_size_t),
|
|
167
|
+
("PeakProcessMemoryUsed", ctypes.c_size_t),
|
|
168
|
+
("PeakJobMemoryUsed", ctypes.c_size_t),
|
|
169
|
+
]
|
|
170
|
+
|
|
171
|
+
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
|
172
|
+
kernel32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
|
|
173
|
+
kernel32.CreateJobObjectW.restype = wintypes.HANDLE
|
|
174
|
+
kernel32.SetInformationJobObject.argtypes = [
|
|
175
|
+
wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD
|
|
176
|
+
]
|
|
177
|
+
kernel32.SetInformationJobObject.restype = wintypes.BOOL
|
|
178
|
+
kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
|
|
179
|
+
kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
|
|
180
|
+
kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
|
|
181
|
+
kernel32.OpenProcess.restype = wintypes.HANDLE
|
|
182
|
+
kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
|
|
183
|
+
kernel32.CloseHandle.restype = wintypes.BOOL
|
|
184
|
+
kernel32.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]
|
|
185
|
+
kernel32.TerminateJobObject.restype = wintypes.BOOL
|
|
186
|
+
|
|
187
|
+
def dispose_job(handle) -> list[str]:
|
|
188
|
+
"""Best-effort termination and checked close, retrying one failed close."""
|
|
189
|
+
failures = []
|
|
190
|
+
if not kernel32.TerminateJobObject(handle, 1):
|
|
191
|
+
failures.append(f"TerminateJobObject failed (WinError {ctypes.get_last_error()})")
|
|
192
|
+
if not kernel32.CloseHandle(handle):
|
|
193
|
+
first_error = ctypes.get_last_error()
|
|
194
|
+
if not kernel32.CloseHandle(handle):
|
|
195
|
+
failures.append(
|
|
196
|
+
"CloseHandle(Job) failed twice "
|
|
197
|
+
f"(WinError {first_error}, {ctypes.get_last_error()})"
|
|
198
|
+
)
|
|
199
|
+
return failures
|
|
200
|
+
|
|
201
|
+
job = kernel32.CreateJobObjectW(None, None)
|
|
202
|
+
if not job:
|
|
203
|
+
raise ctypes.WinError(ctypes.get_last_error())
|
|
204
|
+
process_handle = None
|
|
205
|
+
primary_error = None
|
|
206
|
+
primary_traceback = None
|
|
207
|
+
cleanup_errors = []
|
|
208
|
+
try:
|
|
209
|
+
limits = ExtendedLimitInformation()
|
|
210
|
+
limits.BasicLimitInformation.LimitFlags = 0x00002000 # KILL_ON_JOB_CLOSE
|
|
211
|
+
if not kernel32.SetInformationJobObject(
|
|
212
|
+
job, 9, ctypes.byref(limits), ctypes.sizeof(limits)
|
|
213
|
+
):
|
|
214
|
+
raise ctypes.WinError(ctypes.get_last_error())
|
|
215
|
+
# Obtain documented Win32 access rights by PID, not CPython's private Popen handle.
|
|
216
|
+
process_handle = kernel32.OpenProcess(
|
|
217
|
+
0x0100 | 0x0001, # PROCESS_SET_QUOTA | PROCESS_TERMINATE
|
|
218
|
+
False,
|
|
219
|
+
process.pid,
|
|
220
|
+
)
|
|
221
|
+
if not process_handle:
|
|
222
|
+
raise ctypes.WinError(ctypes.get_last_error())
|
|
223
|
+
if not kernel32.AssignProcessToJobObject(job, process_handle):
|
|
224
|
+
raise ctypes.WinError(ctypes.get_last_error())
|
|
225
|
+
except BaseException as exc:
|
|
226
|
+
primary_error = exc
|
|
227
|
+
primary_traceback = exc.__traceback__
|
|
228
|
+
cleanup_errors.extend(dispose_job(job))
|
|
229
|
+
finally:
|
|
230
|
+
if process_handle and not kernel32.CloseHandle(process_handle):
|
|
231
|
+
first_error = ctypes.get_last_error()
|
|
232
|
+
if not kernel32.CloseHandle(process_handle):
|
|
233
|
+
cleanup_errors.append(
|
|
234
|
+
"CloseHandle(process) failed twice "
|
|
235
|
+
f"(WinError {first_error}, {ctypes.get_last_error()})"
|
|
236
|
+
)
|
|
237
|
+
# If assignment succeeded, dispose the Job so the CLI cannot
|
|
238
|
+
# outlive this failed setup path.
|
|
239
|
+
if primary_error is None:
|
|
240
|
+
cleanup_errors.extend(dispose_job(job))
|
|
241
|
+
elif primary_error is None:
|
|
242
|
+
# The first close failed but the retry succeeded; surface the
|
|
243
|
+
# API failure rather than silently accepting an abnormal close.
|
|
244
|
+
cleanup_errors.append(
|
|
245
|
+
f"CloseHandle(process) initially failed (WinError {first_error})"
|
|
246
|
+
)
|
|
247
|
+
cleanup_errors.extend(dispose_job(job))
|
|
248
|
+
|
|
249
|
+
if primary_error is not None:
|
|
250
|
+
if cleanup_errors:
|
|
251
|
+
raise RuntimeError(
|
|
252
|
+
"Windows Job Object setup failed and cleanup was incomplete: "
|
|
253
|
+
+ "; ".join(cleanup_errors)
|
|
254
|
+
) from primary_error
|
|
255
|
+
raise primary_error.with_traceback(primary_traceback)
|
|
256
|
+
if cleanup_errors:
|
|
257
|
+
raise RuntimeError(
|
|
258
|
+
"Windows Job Object setup could not release its process handle: "
|
|
259
|
+
+ "; ".join(cleanup_errors)
|
|
260
|
+
)
|
|
261
|
+
return job
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def _close_windows_job(job) -> None:
|
|
265
|
+
"""Close a Job Object; KILL_ON_JOB_CLOSE terminates all remaining members."""
|
|
266
|
+
if job is None:
|
|
267
|
+
return
|
|
268
|
+
import ctypes
|
|
269
|
+
from ctypes import wintypes
|
|
270
|
+
|
|
271
|
+
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
|
272
|
+
kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
|
|
273
|
+
kernel32.CloseHandle.restype = wintypes.BOOL
|
|
274
|
+
kernel32.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]
|
|
275
|
+
kernel32.TerminateJobObject.restype = wintypes.BOOL
|
|
276
|
+
if not kernel32.CloseHandle(job):
|
|
277
|
+
close_error = ctypes.WinError(ctypes.get_last_error())
|
|
278
|
+
# A failed close must not degrade to killing only the CLI leader: the
|
|
279
|
+
# Job may still own descendants that inherited the output handles.
|
|
280
|
+
if not kernel32.TerminateJobObject(job, 1):
|
|
281
|
+
terminate_error = ctypes.WinError(ctypes.get_last_error())
|
|
282
|
+
raise RuntimeError(
|
|
283
|
+
"could not close or terminate the GitHub CLI Job Object"
|
|
284
|
+
) from terminate_error
|
|
285
|
+
if not kernel32.CloseHandle(job):
|
|
286
|
+
raise ctypes.WinError(ctypes.get_last_error()) from close_error
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def _kill_and_reap_cli(
|
|
290
|
+
process: subprocess.Popen[bytes], windows_job=None
|
|
291
|
+
) -> None:
|
|
292
|
+
"""Stop the isolated CLI process tree where supported, then reap its leader."""
|
|
293
|
+
if os.name == "posix":
|
|
294
|
+
try:
|
|
295
|
+
os.killpg(process.pid, signal.SIGKILL)
|
|
296
|
+
except ProcessLookupError:
|
|
297
|
+
pass
|
|
298
|
+
except OSError:
|
|
299
|
+
# Retain a direct-child fallback if process-group signaling is unavailable.
|
|
300
|
+
if process.poll() is None:
|
|
301
|
+
try:
|
|
302
|
+
process.kill()
|
|
303
|
+
except ProcessLookupError:
|
|
304
|
+
pass
|
|
305
|
+
elif windows_job is not None:
|
|
306
|
+
_close_windows_job(windows_job)
|
|
307
|
+
elif process.poll() is None:
|
|
308
|
+
try:
|
|
309
|
+
process.kill()
|
|
310
|
+
except ProcessLookupError:
|
|
311
|
+
pass
|
|
312
|
+
process.wait()
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
def _run_cli_bounded(
|
|
316
|
+
command: list[str],
|
|
317
|
+
*,
|
|
318
|
+
timeout: int,
|
|
319
|
+
output_dir: Path,
|
|
320
|
+
stdout_limit: int,
|
|
321
|
+
stderr_limit: int = GH_STDERR_LIMIT_BYTES,
|
|
322
|
+
) -> subprocess.CompletedProcess[str]:
|
|
323
|
+
"""Run a CLI with bounded output checks and a wall-clock deadline."""
|
|
324
|
+
stdout_path = output_dir / "cli-stdout"
|
|
325
|
+
stderr_path = output_dir / "cli-stderr"
|
|
326
|
+
deadline = time.monotonic() + timeout
|
|
327
|
+
with stdout_path.open("wb") as stdout_file, stderr_path.open("wb") as stderr_file:
|
|
328
|
+
process = subprocess.Popen(
|
|
329
|
+
command,
|
|
330
|
+
stdout=stdout_file,
|
|
331
|
+
stderr=stderr_file,
|
|
332
|
+
text=False,
|
|
333
|
+
start_new_session=(os.name == "posix"),
|
|
334
|
+
)
|
|
335
|
+
windows_job = None
|
|
336
|
+
try:
|
|
337
|
+
if os.name == "nt":
|
|
338
|
+
windows_job = _create_windows_job(process)
|
|
339
|
+
except BaseException:
|
|
340
|
+
_kill_and_reap_cli(process)
|
|
341
|
+
raise
|
|
342
|
+
failure = None
|
|
343
|
+
try:
|
|
344
|
+
while True:
|
|
345
|
+
try:
|
|
346
|
+
returncode = process.wait(
|
|
347
|
+
timeout=min(0.05, max(0.0, deadline - time.monotonic()))
|
|
348
|
+
)
|
|
349
|
+
break
|
|
350
|
+
except subprocess.TimeoutExpired:
|
|
351
|
+
stdout_size = stdout_path.stat().st_size
|
|
352
|
+
stderr_size = stderr_path.stat().st_size
|
|
353
|
+
if stdout_size > stdout_limit:
|
|
354
|
+
failure = RuntimeError(
|
|
355
|
+
f"GitHub CLI stdout exceeded the {stdout_limit}-byte limit"
|
|
356
|
+
)
|
|
357
|
+
break
|
|
358
|
+
if stderr_size > stderr_limit:
|
|
359
|
+
failure = RuntimeError(
|
|
360
|
+
f"GitHub CLI stderr exceeded the {stderr_limit}-byte limit"
|
|
361
|
+
)
|
|
362
|
+
break
|
|
363
|
+
if time.monotonic() >= deadline:
|
|
364
|
+
failure = subprocess.TimeoutExpired(command, timeout)
|
|
365
|
+
break
|
|
366
|
+
|
|
367
|
+
# Also stop descendants that inherited the output handles. On POSIX,
|
|
368
|
+
# start_new_session gives this CLI an isolated process group.
|
|
369
|
+
_kill_and_reap_cli(process, windows_job)
|
|
370
|
+
windows_job = None
|
|
371
|
+
except BaseException:
|
|
372
|
+
try:
|
|
373
|
+
_kill_and_reap_cli(process, windows_job)
|
|
374
|
+
windows_job = None
|
|
375
|
+
except BaseException:
|
|
376
|
+
# Preserve the operation's original failure after attempting cleanup.
|
|
377
|
+
if process.poll() is None:
|
|
378
|
+
try:
|
|
379
|
+
process.kill()
|
|
380
|
+
except ProcessLookupError:
|
|
381
|
+
pass
|
|
382
|
+
process.wait()
|
|
383
|
+
raise
|
|
384
|
+
stdout_file.flush()
|
|
385
|
+
stderr_file.flush()
|
|
386
|
+
|
|
387
|
+
if failure is not None:
|
|
388
|
+
raise failure
|
|
389
|
+
stdout_size = stdout_path.stat().st_size
|
|
390
|
+
stderr_size = stderr_path.stat().st_size
|
|
391
|
+
if stdout_size > stdout_limit:
|
|
392
|
+
raise RuntimeError(f"GitHub CLI stdout exceeded the {stdout_limit}-byte limit")
|
|
393
|
+
if stderr_size > stderr_limit:
|
|
394
|
+
raise RuntimeError(f"GitHub CLI stderr exceeded the {stderr_limit}-byte limit")
|
|
395
|
+
with stdout_path.open("rb") as stream:
|
|
396
|
+
stdout = stream.read(stdout_limit + 1).decode("utf-8", errors="replace")
|
|
397
|
+
with stderr_path.open("rb") as stream:
|
|
398
|
+
stream.seek(max(0, stderr_size - GH_STDERR_TAIL_BYTES))
|
|
399
|
+
stderr = stream.read(GH_STDERR_TAIL_BYTES).decode("utf-8", errors="replace")
|
|
400
|
+
return subprocess.CompletedProcess(command, returncode, stdout, stderr)
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
def _version_tuple(output: str) -> tuple[int, int, int]:
|
|
404
|
+
first_line = output.splitlines()[0].strip() if output.splitlines() else ""
|
|
405
|
+
match = GH_VERSION_RE.fullmatch(first_line)
|
|
406
|
+
if not match:
|
|
407
|
+
raise RuntimeError("could not parse GitHub CLI version; require gh >= 2.102.0")
|
|
408
|
+
return tuple(int(part) for part in match.groups())
|
|
409
|
+
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
def _sha256_file(path: Path) -> str:
|
|
413
|
+
"""Hash a file incrementally so large artifacts do not require a full-size allocation."""
|
|
414
|
+
digest = hashlib.sha256()
|
|
415
|
+
with path.open("rb") as stream:
|
|
416
|
+
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
|
|
417
|
+
digest.update(chunk)
|
|
418
|
+
return digest.hexdigest()
|
|
419
|
+
|
|
420
|
+
def _validate_verified_statements(
|
|
421
|
+
verified: Any, expected_sha256: str, expected_repository_id: int | None = None
|
|
422
|
+
) -> int:
|
|
423
|
+
if not isinstance(verified, list) or not verified:
|
|
424
|
+
raise RuntimeError("gh attestation verify returned no verified attestations")
|
|
425
|
+
for item in verified:
|
|
426
|
+
if not isinstance(item, dict):
|
|
427
|
+
raise RuntimeError("gh attestation verify returned an unexpected result schema")
|
|
428
|
+
result = item.get("verificationResult")
|
|
429
|
+
statement = result.get("statement") if isinstance(result, dict) else None
|
|
430
|
+
if not isinstance(statement, dict):
|
|
431
|
+
raise RuntimeError("verified attestation is missing its in-toto statement")
|
|
432
|
+
if statement.get("predicateType") != PREDICATE_TYPE:
|
|
433
|
+
raise RuntimeError("verified attestation has an unexpected predicate type")
|
|
434
|
+
subjects = statement.get("subject")
|
|
435
|
+
if not isinstance(subjects, list) or not subjects:
|
|
436
|
+
raise RuntimeError("verified attestation has no subject entries")
|
|
437
|
+
if not any(
|
|
438
|
+
isinstance(subject, dict)
|
|
439
|
+
and isinstance(subject.get("digest"), dict)
|
|
440
|
+
and subject["digest"].get("sha256") == expected_sha256
|
|
441
|
+
for subject in subjects
|
|
442
|
+
):
|
|
443
|
+
raise RuntimeError("verified attestation does not name the exact artifact SHA-256")
|
|
444
|
+
if expected_repository_id is not None:
|
|
445
|
+
signature = result.get("signature")
|
|
446
|
+
certificate = signature.get("certificate") if isinstance(signature, dict) else None
|
|
447
|
+
actual_repository_id = (
|
|
448
|
+
certificate.get("sourceRepositoryIdentifier")
|
|
449
|
+
if isinstance(certificate, dict) else None
|
|
450
|
+
)
|
|
451
|
+
if str(actual_repository_id) != str(expected_repository_id):
|
|
452
|
+
raise RuntimeError(
|
|
453
|
+
"verified attestation certificate repository ID does not match "
|
|
454
|
+
"the expected repository ID"
|
|
455
|
+
)
|
|
456
|
+
return len(verified)
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
def verify_build_provenance(
|
|
460
|
+
artifact: Path,
|
|
461
|
+
*,
|
|
462
|
+
repository: str,
|
|
463
|
+
signer_workflow: str,
|
|
464
|
+
source_ref: str,
|
|
465
|
+
source_digest: str,
|
|
466
|
+
bundle: Path | None = None,
|
|
467
|
+
trusted_root: Path | None = None,
|
|
468
|
+
repository_id: int | None = None,
|
|
469
|
+
gh_bin: str = "gh",
|
|
470
|
+
) -> dict[str, Any]:
|
|
471
|
+
_require_regular_file(artifact, "artifact")
|
|
472
|
+
if not REPO_RE.fullmatch(repository):
|
|
473
|
+
raise ValueError("repository must use owner/repository syntax")
|
|
474
|
+
workflow_prefix = repository + "/.github/workflows/"
|
|
475
|
+
if (
|
|
476
|
+
not signer_workflow.startswith(workflow_prefix)
|
|
477
|
+
or not signer_workflow.endswith((".yml", ".yaml"))
|
|
478
|
+
or "\n" in signer_workflow
|
|
479
|
+
or ".." in signer_workflow
|
|
480
|
+
):
|
|
481
|
+
raise ValueError("signer_workflow must be a workflow file in the expected repository")
|
|
482
|
+
if not _is_valid_git_ref(source_ref):
|
|
483
|
+
raise ValueError("source_ref must be a valid fully qualified Git branch or tag ref")
|
|
484
|
+
if not SHA1_RE.fullmatch(source_digest):
|
|
485
|
+
raise ValueError("source_digest must be a full lowercase 40-character Git commit SHA")
|
|
486
|
+
if bundle is not None:
|
|
487
|
+
_require_regular_file(bundle, "bundle")
|
|
488
|
+
if bundle is not None:
|
|
489
|
+
if repository_id is None or repository_id <= 0:
|
|
490
|
+
raise ValueError("offline bundle verification requires a positive --repository-id")
|
|
491
|
+
if trusted_root is None:
|
|
492
|
+
raise ValueError("offline bundle verification requires --trusted-root")
|
|
493
|
+
if repository_id is not None and repository_id <= 0:
|
|
494
|
+
raise ValueError("repository_id must be a positive integer")
|
|
495
|
+
if repository_id is not None and bundle is None:
|
|
496
|
+
raise ValueError("repository_id can only be used with an offline bundle")
|
|
497
|
+
if trusted_root is not None:
|
|
498
|
+
if bundle is None:
|
|
499
|
+
raise ValueError("trusted_root can only be used with an offline bundle")
|
|
500
|
+
_require_regular_file(trusted_root, "trusted_root")
|
|
501
|
+
|
|
502
|
+
executable = shutil.which(gh_bin)
|
|
503
|
+
if executable is None:
|
|
504
|
+
raise RuntimeError("GitHub CLI (gh) is required for cryptographic attestation verification")
|
|
505
|
+
|
|
506
|
+
# Keep CLI output files inside the private workspace and remove them on exit.
|
|
507
|
+
with tempfile.TemporaryDirectory(prefix="slsa-verify-") as temp_dir:
|
|
508
|
+
snapshot_dir = Path(temp_dir)
|
|
509
|
+
artifact_snapshot = snapshot_dir / "artifact" / artifact.name
|
|
510
|
+
artifact_snapshot.parent.mkdir()
|
|
511
|
+
_copy_regular_file_snapshot(artifact, artifact_snapshot, "artifact")
|
|
512
|
+
artifact_sha256 = _sha256_file(artifact_snapshot)
|
|
513
|
+
bundle_snapshot = None
|
|
514
|
+
if bundle is not None:
|
|
515
|
+
bundle_snapshot = snapshot_dir / "bundle" / bundle.name
|
|
516
|
+
bundle_snapshot.parent.mkdir()
|
|
517
|
+
_copy_regular_file_snapshot(bundle, bundle_snapshot, "bundle")
|
|
518
|
+
trusted_root_snapshot = None
|
|
519
|
+
if trusted_root is not None:
|
|
520
|
+
trusted_root_snapshot = snapshot_dir / "trusted-root" / trusted_root.name
|
|
521
|
+
trusted_root_snapshot.parent.mkdir()
|
|
522
|
+
_copy_regular_file_snapshot(trusted_root, trusted_root_snapshot, "trusted_root")
|
|
523
|
+
|
|
524
|
+
try:
|
|
525
|
+
version = _run_cli_bounded(
|
|
526
|
+
[executable, "version"],
|
|
527
|
+
timeout=GH_VERSION_TIMEOUT_SECONDS,
|
|
528
|
+
output_dir=snapshot_dir,
|
|
529
|
+
stdout_limit=GH_VERSION_STDOUT_LIMIT_BYTES,
|
|
530
|
+
)
|
|
531
|
+
except subprocess.TimeoutExpired as exc:
|
|
532
|
+
raise RuntimeError("timed out while determining GitHub CLI version") from exc
|
|
533
|
+
if version.returncode != 0:
|
|
534
|
+
raise RuntimeError("could not determine GitHub CLI version")
|
|
535
|
+
gh_version = _version_tuple(version.stdout)
|
|
536
|
+
if gh_version < MIN_GH_VERSION:
|
|
537
|
+
raise RuntimeError(
|
|
538
|
+
"GitHub CLI >= 2.102.0 is required; older releases have vulnerable "
|
|
539
|
+
"source-ref and signer-workflow identity matching"
|
|
540
|
+
)
|
|
541
|
+
|
|
542
|
+
command = [
|
|
543
|
+
executable, "attestation", "verify", str(artifact_snapshot),
|
|
544
|
+
"--repo", repository,
|
|
545
|
+
"--signer-workflow", signer_workflow,
|
|
546
|
+
"--source-ref", source_ref,
|
|
547
|
+
"--source-digest", source_digest,
|
|
548
|
+
"--cert-oidc-issuer", OIDC_ISSUER,
|
|
549
|
+
"--predicate-type", PREDICATE_TYPE,
|
|
550
|
+
"--deny-self-hosted-runners",
|
|
551
|
+
"--format", "json",
|
|
552
|
+
]
|
|
553
|
+
if bundle is not None:
|
|
554
|
+
command.extend(["--bundle", str(bundle_snapshot)])
|
|
555
|
+
if trusted_root is not None:
|
|
556
|
+
command.extend(["--custom-trusted-root", str(trusted_root_snapshot)])
|
|
557
|
+
try:
|
|
558
|
+
completed = _run_cli_bounded(
|
|
559
|
+
command,
|
|
560
|
+
timeout=GH_VERIFY_TIMEOUT_SECONDS,
|
|
561
|
+
output_dir=snapshot_dir,
|
|
562
|
+
stdout_limit=GH_VERIFY_STDOUT_LIMIT_BYTES,
|
|
563
|
+
)
|
|
564
|
+
except subprocess.TimeoutExpired as exc:
|
|
565
|
+
raise RuntimeError(
|
|
566
|
+
f"gh attestation verify timed out after {GH_VERIFY_TIMEOUT_SECONDS} seconds"
|
|
567
|
+
) from exc
|
|
568
|
+
if completed.returncode != 0:
|
|
569
|
+
detail = (completed.stderr or completed.stdout or "no diagnostic output").strip()
|
|
570
|
+
raise RuntimeError("gh attestation verify rejected the artifact: " + detail[-GH_STDERR_TAIL_BYTES:])
|
|
571
|
+
try:
|
|
572
|
+
verified = json.loads(completed.stdout)
|
|
573
|
+
except json.JSONDecodeError as exc:
|
|
574
|
+
raise RuntimeError("gh attestation verify returned invalid JSON despite success") from exc
|
|
575
|
+
count = _validate_verified_statements(verified, artifact_sha256, repository_id if bundle is not None else None)
|
|
576
|
+
|
|
577
|
+
return {
|
|
578
|
+
"verified": True,
|
|
579
|
+
"verification_tool": "gh attestation verify",
|
|
580
|
+
"minimum_gh_version": "2.102.0",
|
|
581
|
+
"repository": repository,
|
|
582
|
+
"signer_workflow": signer_workflow,
|
|
583
|
+
"source_ref": source_ref,
|
|
584
|
+
"source_digest": source_digest,
|
|
585
|
+
"predicate_type": PREDICATE_TYPE,
|
|
586
|
+
"oidc_issuer": OIDC_ISSUER,
|
|
587
|
+
"self_hosted_runners_denied": True,
|
|
588
|
+
"artifact_sha256": artifact_sha256,
|
|
589
|
+
"verified_attestation_count": count,
|
|
590
|
+
}
|
|
591
|
+
|
|
592
|
+
|
|
593
|
+
def main() -> int:
|
|
594
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
595
|
+
parser.add_argument("artifact", type=Path)
|
|
596
|
+
parser.add_argument("--repo", required=True, dest="repository")
|
|
597
|
+
parser.add_argument("--signer-workflow", required=True)
|
|
598
|
+
parser.add_argument("--source-ref", required=True)
|
|
599
|
+
parser.add_argument("--source-digest", required=True)
|
|
600
|
+
parser.add_argument("--bundle", type=Path, help="Previously downloaded attestation bundle (JSON or JSONL)")
|
|
601
|
+
parser.add_argument("--trusted-root", type=Path, help="Explicit Sigstore trusted-root JSONL for offline verification; requires --bundle")
|
|
602
|
+
parser.add_argument("--repository-id", type=int, help="Expected numeric GitHub repository ID; required with --bundle")
|
|
603
|
+
parser.add_argument("--gh-bin", default="gh", help="GitHub CLI executable (default: gh)")
|
|
604
|
+
args = parser.parse_args()
|
|
605
|
+
try:
|
|
606
|
+
result = verify_build_provenance(
|
|
607
|
+
args.artifact,
|
|
608
|
+
repository=args.repository,
|
|
609
|
+
signer_workflow=args.signer_workflow,
|
|
610
|
+
source_ref=args.source_ref,
|
|
611
|
+
source_digest=args.source_digest,
|
|
612
|
+
bundle=args.bundle,
|
|
613
|
+
trusted_root=args.trusted_root,
|
|
614
|
+
repository_id=args.repository_id,
|
|
615
|
+
gh_bin=args.gh_bin,
|
|
616
|
+
)
|
|
617
|
+
except (OSError, ValueError, RuntimeError) as exc:
|
|
618
|
+
print("ERROR: " + str(exc), file=sys.stderr)
|
|
619
|
+
return 1
|
|
620
|
+
print(json.dumps(result, sort_keys=True, indent=2))
|
|
621
|
+
return 0
|
|
622
|
+
|
|
623
|
+
|
|
624
|
+
if __name__ == "__main__":
|
|
625
|
+
raise SystemExit(main())
|