.nh
.TH "GH-ATTESTATION-VERIFY" "1" "Sep 2026" "" "GitHub CLI manual"

.SH "نام (NAME)"
gh-attestation-verify \- اعتبارسنجی تاییدیه یک آرتفکت یا باینری


.SH "خلاصه دستور (SYNOPSIS)"
\fBgh attestation verify [<file-path> | oci://<image-uri>] [--owner | --repo] [flags]\fR


.SH "توضیحات (DESCRIPTION)"
اعتبارسنجی یکپارچگی و اصالت یک آرتفکت با استفاده از تاییدیه‌های امضاشده به روش رمزنگاری مرتبط با آن\&.

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

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

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

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

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

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

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

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

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

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

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

.SH "بارگذاری آرتفکت‌ها و تاییدیه‌ها (Loading Artifacts And Attestations)"
برای مشخص کردن آرتفکت، این دستور به یکی از موارد زیر نیاز دارد:
* مسیر فایل به یک آرتفکت، یا
* یک شناسه منبع تصویر کانتینر (مانند
.BR "oci://<image\-uri>" )
  * (توجه داشته باشید که در صورت ارائه یک نشانی اینترنتی OCI، باید از قبل در رجیستری کانتینر آن احراز هویت شده باشید)

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

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

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

.SH "اعمال سیاست‌های تکمیلی (Additional Policy Enforcement)"
در صورت استفاده از گزینه
.BR \-\-format=json ،
پس از اعتبارسنجی موفقیت‌آمیز، این دستور یک آرایه JSON شامل یک مدخل به ازای هر تاییدیه اعتبارسنجی‌شده را در خروجی چاپ می‌کند\&.

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

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

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

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

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

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

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

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


.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-b\fR, \fB\-\-bundle\fR \fB<string>\fR
مسیر بسته تاییدیه (باندل) روی دیسک، که می‌تواند یک بسته منفرد در یک فایل JSON یا یک فایل خطوط JSON (json lines) حاوی چندین بسته باشد

.TP
\fB\-\-bundle\-from\-oci\fR
هنگام اعتبارسنجی یک تصویر OCI، واکشی بسته تاییدیه از رجیستری OCI به‌جای گیت‌هاب

.TP
\fB\-\-cert\-identity\fR \fB<string>\fR
الزام انطباق دقیق فیلد SubjectAlternativeName گواهی با مقدار ارائه‌شده

.TP
\fB\-i\fR, \fB\-\-cert\-identity\-regex\fR \fB<string>\fR
الزام انطباق فیلد SubjectAlternativeName گواهی با عبارت باقاعده (regex) ارائه‌شده

.TP
\fB\-\-cert\-oidc\-issuer\fR \fB<string> (default "https://token.actions.githubusercontent.com")\fR
الزام انطباق صادرکننده توکن OIDC با مقدار ارائه‌شده

.TP
\fB\-\-custom\-trusted\-root\fR \fB<string>\fR
مسیر به یک فایل trusted_root.jsonl؛ احتمالاً برای اعتبارسنجی آفلاین

.TP
\fB\-\-deny\-self\-hosted\-runners\fR
رد کردن اعتبارسنجی برای تاییدیه‌های تولیدشده روی رانرهای میزبانی‌شده توسط خود (self-hosted)

.TP
\fB\-d\fR, \fB\-\-digest\-alg\fR \fB<string> (default "sha256")\fR
الگوریتم مورداستفاده برای محاسبه چکیده (digest) آرتفکت: {sha256|sha512}

.TP
\fB\-\-format\fR \fB<string>\fR
قالب خروجی: {json}

.TP
\fB\-\-hostname\fR \fB<string>\fR
پیکربندی میزبان (host) مورد استفاده

.TP
\fB\-q\fR, \fB\-\-jq\fR \fB<expression>\fR
فیلتر کردن خروجی JSON با استفاده از یک عبارت jq

.TP
\fB\-L\fR, \fB\-\-limit\fR \fB<int> (default 30)\fR
حداکثر تعداد تاییدیه‌ها برای واکشی

.TP
\fB\-\-no\-public\-good\fR
عدم اعتبارسنجی تاییدیه‌های امضاشده با نمونه عمومی سیگ‌استور (Sigstore public good instance)

.TP
\fB\-o\fR, \fB\-\-owner\fR \fB<string>\fR
سازمان گیت‌هاب جهت محدود کردن دامنه جستجوی تاییدیه

.TP
\fB\-\-predicate\-type\fR \fB<string> (default "https://slsa.dev/provenance/v1")\fR
الزام انطباق نوع گزاره (predicate type) تاییدیه‌های اعتبارسنجی‌شده با مقدار ارائه‌شده

.TP
\fB\-R\fR, \fB\-\-repo\fR \fB<string>\fR
نام مخزن در قالب [HOST/]OWNER/REPO

.TP
\fB\-\-signer\-digest\fR \fB<string>\fR
الزام انطباق چکیده (digest) مرتبط با گردش‌کار امضاکننده با مقدار ارائه‌شده

.TP
\fB\-\-signer\-repo\fR \fB<string>\fR
الزام انطباق مخزن گردش‌کاری که تاییدیه را امضا کرده است با مقدار ارائه‌شده ([HOST/]OWNER/REPO)

.TP
\fB\-\-signer\-workflow\fR \fB<string>\fR
الزام انطباق گردش‌کاری که تاییدیه را امضا کرده است با مقدار ارائه‌شده ([host/]owner/repo/workflow_path)

.TP
\fB\-\-source\-digest\fR \fB<string>\fR
الزام انطباق چکیده (digest) مرتبط با مخزن مبدا با مقدار ارائه‌شده

.TP
\fB\-\-source\-ref\fR \fB<string>\fR
الزام انطباق ارجاع گیت (git ref) مرتبط با مخزن مبدا با مقدار ارائه‌شده

.TP
\fB\-t\fR, \fB\-\-template\fR \fB<string>\fR
قالب‌بندی خروجی JSON با استفاده از یک الگوی Go؛ دستور "gh help formatting" را ببینید


.SH "کدهای خروج (EXIT CODES)"
0: اجرای موفقیت‌آمیز

.PP
1: خطا

.PP
2: لغو دستور

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

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


.SH "مثال‌ها (EXAMPLES)"
.EX
# اعتبارسنجی یک آرتفکت مرتبط با یک مخزن
$ 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

.EE


.SH "همچنین ببینید (SEE ALSO)"
\fBgh-attestation(1)\fR