وثائق Guardrail Ledger

ربط مسار البناء

تعمل الماسحات على وكلائك أو مشغّلاتك. تجمع المهمة أو الإجراء ملفات SARIF الخاصة بها، وترسلها إلى مساحة العمل، وتقرأ نتيجة البوابة.

1. أنشئ رمز إدخال

يفتح المالك أو المسؤول صفحة المسار، ويدخل اسمًا للرمز، ويختار إنشاء رمز إدخال. يظهر الرمز مرة واحدة. خزّنه كمتغير سري باسم GUARDRAIL_TOKEN في Azure Pipelines، أو كسر مستودع باسم GUARDRAIL_INGEST_TOKEN على GitHub.

2. ثبّت الماسحات الأربعة

يجب أن تكون Trivy وGitleaks وCheckov وOpengrep ضمن PATH الخاص بالوكيل أو المشغّل. لا تثبّتها المهمة.

3أ. Azure DevOps

1. في صفحة المسار، أدخل اسم مؤسسة Azure DevOps الخاصة بك (الاسم الوارد في dev.azure.com/<organisation>) واختر مشاركة الامتداد مع هذه المؤسسة.
2. افتح رابط Marketplace الذي يظهر هناك، واختر الحصول عليه مجانًا، ثم اختر المؤسسة. يتطلب التثبيت إذنًا بإدارة الامتدادات في تلك المؤسسة. ما لم تتم مشاركة الامتداد، لا يظهر الرابط.
3. أضف الخطوة إلى azure-pipelines.yml وشغّل المسار على طلبات السحب.

- task: GuardrailLedgerScan@0
  inputs:
    guardrailUrl: 'https://<workspace>.guardrail-ledger.com'
    ingestToken: '$(GUARDRAIL_TOKEN)'
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

يتيح سطر env للمهمة التعليق بنتيجة البوابة على طلب السحب. كما تحتاج هوية خدمة البناء الخاصة بالمشروع إلى إذن المساهمة في طلبات السحب (Contribute to pull requests) على المستودع.

3ب. GitHub Actions

1. في صفحة المسار، نزّل action.yml وindex.js. أودِعهما (commit) باسم .github/actions/guardrail-ledger/action.yml و.github/actions/guardrail-ledger/dist/index.js.
2. أضف سير العمل الذي تعرضه صفحة المسار. يثبّت الماسحات، ثم يشغّل الإجراء بعنوان مساحة العمل الخاصة بك والسر GUARDRAIL_INGEST_TOKEN.
3. شغّل الفحص على طلبات السحب القادمة من فروع (branches) داخل المستودع. في النسخ المتفرعة (forks) لا يمنح GitHub المهمة أي أسرار.

تحتاج المهمة إلى هذه الأذونات كي يتمكن الإجراء من قراءة الشيفرة والتعليق على طلب السحب:

permissions:
  contents: read
  pull-requests: write

أي نظام CI آخر

يمكن لأي نظام CI يكتب SARIF إرساله إلى مساحة العمل الخاصة بك. المحتوى بصيغة JSON ويتضمن repo وsarif، ويوضع الرمز في ترويسة Bearer.

curl -sS -X POST 'https://<workspace>.guardrail-ledger.com/api/v1/ingest/sarif' \
  -H "Authorization: Bearer $GUARDRAIL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"repo":"example-repo","sarif":{"version":"2.1.0","runs":[...]}}'

عند فشل ماسح

تفشل الخطوة وتذكر اسم الماسح عندما يكون الماسح مفقودًا أو ينهار أو ينتهي بخطأ أو لا يكتب SARIF صالحًا للاستخدام. لا يُرسل شيء في هذه الحالة. لمتابعة العمل بالماسحات الأخرى، اضبط allowMissingScanners: true على مهمة Azure DevOps، أو allow-missing-scanners: true على الإجراء. عندها يُرسل التشغيل على أنه غير مكتمل، فلا تُحَلّ أي نتيجة بناءً عليه، ولا تجتاز البوابة بسبب ما هو مفقود.

ما الذي يُرسل

ترسل المهمة نتائج SARIF الخاصة بالماسحات، واسم المستودع، والالتزام (commit)، ورقم طلب السحب، واسم دخول الشخص الذي شغّل البناء، ومسارات ملفات أدوات الذكاء الاصطناعي مثل AGENTS.md أو mcp.json. وتزيل مقتطفات الشيفرة وأسطر السياق من SARIF قبل الإرسال. ولا ترفع المستودع. يُكتب خرج الماسحات في المجلد المؤقت للوكيل، خارج المصادر، ويُحذف بعد قراءته.