divyanshukumar0014/shipproofأدلة SOC 2 التي تجمع نفسها في GitLab CI: كل عملية دمج تُصدر حزمة موقّعة، وبوابة OPA تحجب الإصدارات التي تفتقر إلى الإثبات، ويحصل المدققون على رابط واحد بدلاً من لقطات الشاشة.
أدلة SOC 2 التي تجمع نفسها بنفسها في GitLab CI: كل عملية دمج تُصدر حزمة موقّعة، وبوابة Open Policy Agent تحظر الإصدارات التي تفتقر إلى الأدلة، ويحصل المدقق على رابط حزمة واحد بدلاً من لقطات الشاشة.
لوحة تحكم المدقق المباشرة · مشروع GitLab · أدلة تجريبية · خارطة الطريق
بنيت ShipProof لأن مبيعات المؤسسات تتوقف مرارًا وتكرارًا أثناء مراجعة أمن المعلومات. عندما يطلب المدقق أدلة إدارة التغيير الخاصة بـ SOC 2 Type II، غالبًا ما يقضي المهندسون أسبوعين في البحث عن لقطات شاشة عبر Jira وSlack وDrive.
أردت أن تعيش الأدلة مباشرة داخل خط أنابيب النشر. كل التزام دمج في ShipProof ينشئ تلقائيًا حزمة أدلة موقّعة وقانونية تغطي تشغيلات الاختبار، وفحوصات Semgrep SAST، والكشف عن الأسرار عبر Gitleaks، وقوائم مكونات البرمجيات Syft، وموافقات CODEOWNERS.
قاعدة التصميم المركزية لديّ صارمة: يمكن لنموذج لغوي كبير (LLM) تلخيص الأدلة أو صياغة أوصاف المشكلات، لكنه لا يمكنه أبدًا الموافقة على إصدار. بوابة الإصدار هي تقييم Open Policy Agent مكتوب بلغة Rego. إذا كان أحد المخرجات مفقودًا أو بدت الموافقة وكأنها ختم مطاطي، فإن البوابة تفشل بشكل مغلق، وتوقف الإصدار، وتفتح مشكلة مع مسار الإصلاح. عندما تسمح البوابة، يحصل المدقق على رابط واحد لموقع ثابت أو لواجهة برمجة تطبيقات موثّقة.
قمت بمقارنة ShipProof مع دورة حياة GitLab DevOps. إنه يؤتمت جميع المراحل التسع أصليًا:
| المرحلة | ما أتمتته في خط الأنابيب |
|---|---|
| plan | إدارة عناصر عمل الفجوات ذات الحلقة المغلقة. حالات رفض البوابة تفتح تلقائيًا مشكلات تتبع منظمة مع أعداد التكرار؛ خطوط الأنابيب الناجحة اللاحقة تحل وتغلق المشكلات تلقائيًا مع مراجع التزام الإصلاح. |
| create | مراجعة الكود وإدارة المصدر. يحمي CODEOWNERS ملفات السياسة؛ ترفض البوابة الموافقات الختمية المطاطية التي تقل عن خمس دقائق؛ ملاحظات MR الآلية توجه المراجعة؛ تدفقات Duo تروي تعليقات MR. |
| verify | تعمل pytest وSemgrep SAST وGitleaks في مرحلة التحقق، وتسجل تجزئات المخرجات. |
| package | يولّد Syft حزم CycloneDX SBOMs في مرحلة الحزم ويجزئ المخرج في الحزمة. |
| secure | تتحقق بوابة OPA الحتمية من التوقيعات وتجزئات السلسلة وقواعد الختم المطاطي قبل الإصدار. |
| release | وظيفة بوابة الامتثال تحظر النشر إلى الإنتاج؛ وظائف النشر تتطلب حكم السماح. |
| configure | تُصيَّر بيانات نشر Cloud Run من متغيرات البيئة دون الالتزام بالأسرار. |
| monitor | تتحقق فحوصات ما بعد النشر من أن ملخصات صور الحاويات قيد التشغيل تطابق الالتزام المعتمد في الحزمة. |
| govern | سجل غير قابل للتغيير مسلسل بالتجزئة يغذي حزم المدقق ومشكلات الفجوات ولوحة تحكم GitLab Pages. |
طوّرت ShipProof باستخدام Python 3.11 وNode.js 20.
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
شغّل مجموعة الاختبارات الخاصة بي وفحوصات الأنواع:
OPA_BIN=/tmp/opa pytest -q && ruff check src tests demo-app scripts && mypy --strict src scripts
اجمع حزمة محلية لأي commit:
PYTHONPATH=src python -m comply.collect --sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --out /tmp/bundle.json
يُخرج المجمّع سطر JSON واحد إلى stdout ويكتب الحزمة الكاملة إلى القرص إلى جانب policy/inputs.json. إذا كانت البراهين مفقودة، تسجّل الحزمة حالة رفض.
PYTHONPATH=src python -m comply.collect --sha <40-hex-sha> --out evidence/bundle.json \
--mr-iid 42 --pipeline-id 1001 --project group/project \
--pipeline-file pipeline.json --approvals-file approvals.json
في CI، يُعدّ scripts/gate_bridge.py ملف pipeline.json، بينما يجلب scripts/fetch_approvals.py بيانات المراجعة من GitLab API. تُسجَّل الملفات المفقودة بحالة مفقودة بدلًا من افتراض النجاح. يتضمن كل سجل stderr معرّف الارتباط الخاص بالحزمة، وتُقنَّع الأسرار كـ ***.
PYTHONPATH=src python -m comply.gate --bundle evidence/bundle.json --ledger logs/ledger.jsonl
يُشير رمز الخروج 0 إلى قرار بالسماح. ويُشير رمز الخروج 1 إلى رفض مع خطأ منظّم يسمّي الضابط الذي فشل. ويُشير رمز الخروج 2 إلى وسائط غير صالحة. عندما تحجب البوابة في CI، تُشغّل خط الأنابيب python -m comply.gap لفتح مشكلة تتبّع.
PYTHONPATH=src python -m comply.packet --ledger logs/ledger.jsonl --release all \
--out packet.json --csv packet.csv --pdf packet.pdf
يحتوي تصدير CSV على أحد عشر عمودًا: bundle_id,commit_sha,mr_iid,pipeline_id,control,proof_type,status,artifact_sha,approver_ids,policy_sha,created_at. ويُصيَّر ملف PDF من المصدر JSON نفسه عبر CSS الطباعة.
AUDITOR_TOKEN=local-only PYTHONPATH=src uvicorn comply.api:app --port 8000
استعلام الحزم باستخدام مصادقة bearer:
curl -H "Authorization: Bearer local-only" "localhost:8000/api/v1/bundles?mr_iid=42"
توفّر واجهة API نقاط نهاية لاستعلامات الحزم، وحزم الإصدارات، وعمليات تصدير PDF في الخلفية، محمية برموز bearer وحدّ معدّل يبلغ 60 طلبًا في الدقيقة.
cd auditor && npm install && npm run build
تم بناء الواجهة باستخدام React 19 وTypeScript وTailwind CSS. وتُصدَّر كموقع ثابت باستخدام التوجيه بالتجزئة (hash routing)، مما يسمح لها بالعمل مباشرةً على GitLab Pages دون الحاجة إلى إعادة كتابة على الخادم. وعند عدم وجود واجهة برمجية خلفية (backend API)، تستخدم بيانات تجريبية من public/fallback/demo-packets.json.
flowchart LR
A["CI jobs (pytest, Semgrep, Gitleaks, Syft)"] --> B["gate_bridge.py (artifact summary)"]
B --> C["comply.collect (bundle.json + inputs.json)"]
C --> D["comply.sign (Cosign, HMAC fallback)"]
D --> E["ledger.jsonl (hash chain)"]
E --> F["comply.gate (OPA policy + signature + chain)"]
F -->|"deny"| G["comply.gap (gap issue + MR comment)"]
F -->|"allow"| H["deploy jobs (gated)"]
E --> I["comply.packet (JSON, CSV, PDF)"]
I --> J["GitLab Pages dashboard + read API"]
ينفّذ خط الأنابيب اختبارات الوحدات وأدوات فحص الأمان، ويربط المخرجات بجامع الأدلة، ويوقّع الحزمة، ويضيف سجلًا إلى السجل الدفتري. تقيّم مهمة البوابة policy/soc2-v1.rego مقابل الحزمة والتوقيع التشفيري وسلسلة السجل الدفتري. تُخطر حالات الرفض طلب الدمج وتفتح عنصر عمل في GitLab. تفتح التقييمات الناجحة مسار مهام النشر وتنشر حزمة المدقق.