GH-ATTESTATION-VERIFY(1) GitHub CLI manual GH-ATTESTATION-VERIFY(1)

gh-attestation-verify - اعتبارسنجی تاییدیه یک آرتفکت یا باینری

gh attestation verify [<file-path> | oci://<image-uri>] [--owner | --repo] [flags]

اعتبارسنجی یکپارچگی و اصالت یک آرتفکت با استفاده از تاییدیه‌های امضاشده به روش رمزنگاری مرتبط با آن.

یک تاییدیه (attestation) در واقع ادعایی است (یعنی یک گزاره اصالت) که توسط یک عامل (یعنی یک گردش‌کار گیت‌هاب اکشنز) در مورد یک موضوع (یعنی یک آرتفکت) مطرح می‌شود.

به منظور اعتبارسنجی یک تاییدیه، باید یک آرتفکت را مشخص کرده و موارد زیر را تایید کنید: * هویت عاملی که تاییدیه را تولید کرده است * نوع گزاره (predicate type) مورد انتظار برای تاییدیه (ماهیت ادعا)

به‌طور پیش‌فرض، این دستور نوع گزاره https://slsa.dev/provenance/v1 را الزام می‌کند. برای اعتبارسنجی سایر انواع گزاره‌های تاییدیه از گزینه --predicate-type استفاده کنید.

«هویت عامل» شامل موارد زیر است: * مخزن یا مالک مخزنی که آرتفکت با آن مرتبط است * گردش‌کار اکشنز که تاییدیه را تولید کرده است (که با عنوان گردش‌کار امضاکننده یا signer workflow نیز شناخته می‌شود)

سپس این هویت در برابر فیلدهای SourceRepository، SourceRepositoryOwner و SubjectAlternativeName (SAN) در گواهی تاییدیه، و موارد دیگر، اعتبارسنجی می‌شود.

تصمیم‌گیری درباره میزان دقت و سخت‌گیری در اعمال این هویت بر عهده شماست.

در کمترین حالت، این دستور نیازمند یکی از موارد زیر است: * گزینه --owner (مانند --owner github) یا * گزینه --repo (مانند --repo github/example)

هر چه هویت را با دقت بیشتری مشخص کنید، کنترل بیشتری بر تضمین‌های امنیتی ارائه‌شده توسط فرآیند اعتبارسنجی خواهید داشت.

در حالت ایده‌آل، مسیر گردش‌کار امضاکننده نیز با استفاده از گزینه‌های --signer-workflow یا --cert-identity اعتبارسنجی می‌شود.

لطفاً توجه داشته باشید: اگر تاییدیه شما از طریق یک گردش‌کار با قابلیت استفاده مجدد (reusable workflow) تولید شده باشد، آن گردش‌کار قابل استفاده مجدد همان امضاکننده‌ای است که هویتش باید اعتبارسنجی شود. در این وضعیت، باید از گزینه --signer-workflow یا --signer-repo استفاده کنید.

برای گزینه‌های بیشتر، سایر پرچم‌های موجود را مشاهده کنید.

برای مشخص کردن آرتفکت، این دستور به یکی از موارد زیر نیاز دارد: * مسیر فایل به یک آرتفکت، یا * یک شناسه منبع تصویر کانتینر (مانند oci://<image-uri>)
* (توجه داشته باشید که در صورت ارائه یک نشانی اینترنتی OCI، باید از قبل در رجیستری کانتینر آن احراز هویت شده باشید)

به‌طور پیش‌فرض، این دستور تلاش می‌کند با استفاده از مقادیر ارائه‌شده به --owner یا --repo، تاییدیه‌های مربوطه را از طریق رابط برنامه‌نویسی گیت‌هاب (GitHub API) واکشی کند.

برای واکشی تاییدیه‌ها از رجیستری OCI آرتفکت خود به‌جای گیت‌هاب، از گزینه --bundle-from-oci استفاده کنید.

برای اعتبارسنجی آفلاین با استفاده از تاییدیه‌های ذخیره‌شده روی دیسک (دستور download را ببینید)، مسیری را به گزینه --bundle ارائه دهید.

در صورت استفاده از گزینه --format=json، پس از اعتبارسنجی موفقیت‌آمیز، این دستور یک آرایه JSON شامل یک مدخل به ازای هر تاییدیه اعتبارسنجی‌شده را در خروجی چاپ می‌کند.

سپس این خروجی می‌تواند برای اعمال سیاست‌های تکمیلی مورد استفاده قرار گیرد، مثلاً با هدایت (pipe) شدن به یک موتور سیاست‌گذاری (policy engine).

هر شیء در این آرایه شامل دو ویژگی است: * یک شیء attestation، که حاوی بسته تاییدیه (باندل) اعتبارسنجی‌شده است * یک شیء verificationResult، که نمایشی تجزیه‌شده از محتویات بسته تاییدیه اعتبارسنجی‌شده است

درون شیء verificationResult موارد زیر را خواهید یافت: * ویژگی signature.certificate، که نمایشی تجزیه‌شده از گواهی X.509 جاسازی‌شده در تاییدیه است، * ویژگی verifiedTimestamps، آرایه‌ای از اشیاء که زمان ثبت تاییدیه توسط یک گزارش شفافیت (transparency log) یا مرجع برچسب زمانی (timestamp authority) را نشان می‌دهد، * ویژگی statement، که شامل آرایه subject (ارجاع‌دهنده به آرتفکت‌ها)، فیلد predicateType و شیء predicate است که ابرداده‌های اضافی (اغلب قابل کنترل توسط کاربر) را در بر دارد

مهم: لطفاً توجه داشته باشید که تنها ویژگی‌های signature.certificate و verifiedTimestamps حاوی مقادیری هستند که توسط گردش‌کار ایجادکننده تاییدیه قابل دستکاری نیستند.

هنگام کار با تاییدیه‌های ایجادشده در گیت‌هاب اکشنز، محتویات signature.certificate مستقیماً از توکن OpenID Connect تولیدشده توسط گیت‌هاب پر می‌شود. محتویات آرایه verifiedTimestamps نیز از برچسب‌های زمانی امضاشده ناشی از یک گزارش شفافیت یا یک مرجع برچسب زمانی پر می‌شوند و به همین ترتیب توسط کاربران قابل جعل نیستند.

هنگام طراحی فرآیند اعمال سیاست با استفاده از این خروجی، باید در بررسی محتوای ویژگی statement.predicate دقت ویژه‌ای به کار برد: اگر یک مهاجم به بستر اجرای گردش‌کار شما دسترسی پیدا کند، می‌تواند محتویات statement.predicate را جعل کند.

برای کاهش این بردار حمله، استفاده از یک «سازنده معتمد» (trusted builder) را مد نظر قرار دهید: هنگام تولید یک آرتفکت، فرآیند ساخت و امضای تاییدیه را درون یک گردش‌کار با قابلیت استفاده مجدد انجام دهید که اجرای آن نتواند توسط ورودی‌های ارائه‌شده از طریق گردش‌کار فراخواننده تحت تأثیر قرار گیرد.

توضیحات بالا درباره --signer-workflow را ببینید.

مسیر بسته تاییدیه (باندل) روی دیسک، که می‌تواند یک بسته منفرد در یک فایل JSON یا یک فایل خطوط JSON (json lines) حاوی چندین بسته باشد
هنگام اعتبارسنجی یک تصویر OCI، واکشی بسته تاییدیه از رجیستری OCI به‌جای گیت‌هاب
الزام انطباق دقیق فیلد SubjectAlternativeName گواهی با مقدار ارائه‌شده
الزام انطباق فیلد SubjectAlternativeName گواهی با عبارت باقاعده (regex) ارائه‌شده
الزام انطباق صادرکننده توکن OIDC با مقدار ارائه‌شده
مسیر به یک فایل trusted_root.jsonl؛ احتمالاً برای اعتبارسنجی آفلاین
رد کردن اعتبارسنجی برای تاییدیه‌های تولیدشده روی رانرهای میزبانی‌شده توسط خود (self-hosted)
الگوریتم مورداستفاده برای محاسبه چکیده (digest) آرتفکت: {sha256|sha512}
قالب خروجی: {json}
پیکربندی میزبان (host) مورد استفاده
فیلتر کردن خروجی JSON با استفاده از یک عبارت jq
حداکثر تعداد تاییدیه‌ها برای واکشی
عدم اعتبارسنجی تاییدیه‌های امضاشده با نمونه عمومی سیگ‌استور (Sigstore public good instance)
سازمان گیت‌هاب جهت محدود کردن دامنه جستجوی تاییدیه
الزام انطباق نوع گزاره (predicate type) تاییدیه‌های اعتبارسنجی‌شده با مقدار ارائه‌شده
نام مخزن در قالب [HOST/]OWNER/REPO
الزام انطباق چکیده (digest) مرتبط با گردش‌کار امضاکننده با مقدار ارائه‌شده
الزام انطباق مخزن گردش‌کاری که تاییدیه را امضا کرده است با مقدار ارائه‌شده ([HOST/]OWNER/REPO)
الزام انطباق گردش‌کاری که تاییدیه را امضا کرده است با مقدار ارائه‌شده ([host/]owner/repo/workflow_path)
الزام انطباق چکیده (digest) مرتبط با مخزن مبدا با مقدار ارائه‌شده
الزام انطباق ارجاع گیت (git ref) مرتبط با مخزن مبدا با مقدار ارائه‌شده
قالب‌بندی خروجی JSON با استفاده از یک الگوی Go؛ دستور "gh help formatting" را ببینید

0: اجرای موفقیت‌آمیز

1: خطا

2: لغو دستور

4: احراز هویت لازم است

نکته: دستورات خاص ممکن است کدهای خروج دیگری نیز داشته باشند. برای اطلاعات بیشتر به راهنمای دستور مربوطه مراجعه کنید.

# اعتبارسنجی یک آرتفکت مرتبط با یک مخزن
$ gh attestation verify example.bin --repo github/example
# اعتبارسنجی یک آرتفکت مرتبط با یک سازمان
$ gh attestation verify example.bin --owner github
# اعتبارسنجی یک آرتفکت و چاپ نتیجه کامل اعتبارسنجی
$ gh attestation verify example.bin --owner github --format json
# اعتبارسنجی یک تصویر OCI با استفاده از تاییدیه‌های ذخیره‌شده روی دیسک
$ gh attestation verify oci://<image-uri> --owner github --bundle sha256:foo.jsonl
# اعتبارسنجی یک آرتفکت امضاشده با یک گردش‌کار با قابلیت استفاده مجدد
$ gh attestation verify example.bin --owner github --signer-repo actions/example

gh-attestation(1)

Sep 2026