system-design-primer-skill 1.2.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.
Files changed (128) hide show
  1. package/README.md +114 -60
  2. package/SKILL.md +437 -93
  3. package/VERSION +1 -1
  4. package/evals/README.md +1022 -0
  5. package/evals/system-design-cases.json +414 -0
  6. package/package.json +46 -4
  7. package/references/03-data-and-storage.md +8 -2
  8. package/references/04-caching.md +3 -3
  9. package/references/05-async-and-messaging.md +4 -0
  10. package/references/06-distributed-systems.md +2 -2
  11. package/references/07-reliability-and-resilience.md +7 -3
  12. package/references/08-api-security-observability.md +4 -0
  13. package/references/10-workflows-and-checklists.md +1 -1
  14. package/references/13-architecture-intelligence.md +91 -0
  15. package/references/14-api-and-data-contracts.md +80 -0
  16. package/references/15-failure-analysis.md +88 -0
  17. package/references/16-multi-agent-architecture.md +76 -0
  18. package/references/17-agent-harness-and-runtime.md +87 -0
  19. package/references/18-mcp-architecture.md +67 -0
  20. package/references/19-agent-security-and-permissions.md +90 -0
  21. package/references/20-agent-state-and-memory.md +76 -0
  22. package/references/21-agent-evaluation-and-observability.md +90 -0
  23. package/references/22-kubernetes-and-container-platforms.md +29 -0
  24. package/references/23-service-mesh-and-traffic-management.md +21 -0
  25. package/references/24-multi-region-and-disaster-recovery.md +28 -0
  26. package/references/25-platform-engineering-and-developer-experience.md +26 -0
  27. package/references/26-finops-and-cloud-cost.md +29 -0
  28. package/references/27-production-observability-and-slo.md +33 -0
  29. package/references/28-event-streaming-and-kafka-pulsar.md +33 -0
  30. package/references/29-event-sourcing-and-cqrs.md +23 -0
  31. package/references/30-change-data-capture-and-debezium.md +27 -0
  32. package/references/31-data-lakehouse-and-stream-batch.md +24 -0
  33. package/references/32-workflow-orchestration-and-temporal.md +28 -0
  34. package/references/33-schema-registry-and-event-governance.md +22 -0
  35. package/references/34-postgresql-internals-and-performance.md +45 -0
  36. package/references/35-mysql-innodb-and-performance.md +29 -0
  37. package/references/36-sharding-and-distributed-sql.md +22 -0
  38. package/references/37-consensus-and-distributed-transactions.md +29 -0
  39. package/references/38-search-architecture-elasticsearch-opensearch.md +24 -0
  40. package/references/39-vector-databases-and-hybrid-retrieval.md +31 -0
  41. package/references/40-zero-downtime-database-migrations.md +27 -0
  42. package/references/41-api-gateway-and-edge-architecture.md +23 -0
  43. package/references/42-rest-api-design-and-lifecycle.md +23 -0
  44. package/references/43-graphql-architecture-and-governance.md +16 -0
  45. package/references/44-grpc-and-service-contracts.md +16 -0
  46. package/references/45-websocket-sse-and-realtime-systems.md +16 -0
  47. package/references/46-realtime-collaboration-ot-crdt.md +16 -0
  48. package/references/47-api-security-rate-limiting-and-abuse.md +16 -0
  49. package/references/48-oauth-oidc-and-passkeys.md +20 -0
  50. package/references/49-iam-rbac-abac-rebac.md +20 -0
  51. package/references/50-zero-trust-and-workload-identity.md +16 -0
  52. package/references/51-secrets-kms-pki-and-key-management.md +20 -0
  53. package/references/52-supply-chain-security-sbom-slsa.md +78 -0
  54. package/references/53-threat-modeling-stride-and-attack-trees.md +16 -0
  55. package/references/54-privacy-engineering-and-data-governance.md +20 -0
  56. package/references/55-opentelemetry-and-instrumentation.md +54 -0
  57. package/references/56-distributed-tracing-and-context-propagation.md +47 -0
  58. package/references/57-continuous-profiling-and-performance-diagnostics.md +45 -0
  59. package/references/58-load-stress-soak-testing-and-workload-modeling.md +44 -0
  60. package/references/59-capacity-planning-and-performance-modeling.md +38 -0
  61. package/references/60-chaos-engineering-and-resilience-experiments.md +45 -0
  62. package/references/61-incident-management-and-postmortems.md +38 -0
  63. package/references/62-dns-and-service-discovery.md +35 -0
  64. package/references/63-load-balancing-and-global-traffic-management.md +31 -0
  65. package/references/64-cdn-and-edge-caching.md +34 -0
  66. package/references/65-cloud-networking-and-connectivity.md +34 -0
  67. package/references/66-edge-computing-architecture.md +33 -0
  68. package/references/67-storage-infrastructure-and-storage-systems.md +34 -0
  69. package/references/68-tcp-quic-and-network-performance.md +27 -0
  70. package/references/69-task-routing-and-evidence.md +115 -0
  71. package/scripts/audit_chain.py +36 -0
  72. package/scripts/compare_reports.py +43 -0
  73. package/scripts/evaluate.py +475 -0
  74. package/scripts/evaluation_catalog.py +129 -0
  75. package/scripts/evaluation_fingerprints.py +20 -0
  76. package/scripts/evidence_archive.py +79 -0
  77. package/scripts/evidence_signing.py +98 -0
  78. package/scripts/evidence_timestamp.py +441 -0
  79. package/scripts/install.ps1 +12 -3
  80. package/scripts/install.sh +15 -8
  81. package/scripts/report_integrity.py +184 -0
  82. package/scripts/review_consensus.py +77 -0
  83. package/scripts/review_evidence.py +105 -0
  84. package/scripts/review_provenance.py +44 -0
  85. package/scripts/reviewer_calibration.py +215 -0
  86. package/scripts/rubric_compatibility.py +134 -0
  87. package/scripts/run_evals.py +130 -0
  88. package/scripts/run_manifest.py +179 -0
  89. package/scripts/statistical_analysis.py +308 -0
  90. package/scripts/tsa_attestation.py +709 -0
  91. package/scripts/tsa_validation_report.py +627 -0
  92. package/scripts/validate.py +356 -11
  93. package/scripts/verify_build_provenance.py +625 -0
  94. package/scripts/verify_tsa_ocsp.py +962 -0
  95. package/scripts/verify_tsa_revocation.py +782 -0
  96. package/scripts/windows_broker_protocol.py +274 -0
  97. package/scripts/windows_broker_transport.py +141 -0
  98. package/scripts/windows_broker_win32.py +713 -0
  99. package/templates/agent-evaluation-plan-template.md +57 -0
  100. package/templates/agent-security-review-template.md +46 -0
  101. package/templates/agent-system-design-template.md +74 -0
  102. package/templates/api-architecture-design-template.md +33 -0
  103. package/templates/api-security-and-rate-limit-review-template.md +29 -0
  104. package/templates/architecture-decision-matrix-template.md +48 -0
  105. package/templates/architecture-review-scorecard-template.md +36 -0
  106. package/templates/cdc-data-pipeline-template.md +41 -0
  107. package/templates/cdn-and-edge-strategy-template.md +36 -0
  108. package/templates/chaos-experiment-template.md +39 -0
  109. package/templates/cloud-cost-model-template.md +37 -0
  110. package/templates/database-architecture-review-template.md +33 -0
  111. package/templates/edge-computing-readiness-template.md +36 -0
  112. package/templates/event-sourcing-cqrs-template.md +41 -0
  113. package/templates/event-streaming-design-template.md +47 -0
  114. package/templates/failure-analysis-template.md +36 -0
  115. package/templates/identity-and-access-architecture-template.md +29 -0
  116. package/templates/incident-postmortem-template.md +39 -0
  117. package/templates/multi-region-disaster-recovery-template.md +43 -0
  118. package/templates/network-architecture-design-template.md +38 -0
  119. package/templates/observability-architecture-template.md +52 -0
  120. package/templates/performance-test-plan-template.md +52 -0
  121. package/templates/privacy-data-governance-template.md +24 -0
  122. package/templates/production-readiness-checklist-template.md +52 -0
  123. package/templates/realtime-system-design-template.md +28 -0
  124. package/templates/security-threat-model-template.md +26 -0
  125. package/templates/sharding-distributed-sql-design-template.md +34 -0
  126. package/templates/storage-architecture-design-template.md +35 -0
  127. package/templates/supply-chain-security-review-template.md +20 -0
  128. package/templates/zero-downtime-database-migration-template.md +32 -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())