layerleak – ماسح الأسرار لصور OCI

راجع CONTRIBUTING.md للحصول على إرشادات المساهمة.

• ماسح أسرار لصور OCI يعمل مع أي سجل عام متوافق مع OCI (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public، والسجلات المستضافة ذاتياً). يقوم بتحليل طبقات الصورة، والبيانات الوصفية للتكوين، وتاريخ الصورة، ثم يخزن النتائج المكررة المستندة إلى digest المانيفست.
• أدوات المسح التقليدية غالباً ما تتعامل مع صورة الحاوية ككتلة مسطحة أو تعتمد على Daemon Docker محلي. هذا المشروع مصمم حول البنية الداخلية لصور OCI.

المحتويات

• صفحة التوثيق
• الإمكانيات الحالية
• التثبيت
• التخزين الدائم في Postgres
• كيفية البدء
• API عبر HTTP
• نشر Docker Compose (Dockge / Komodo)
• الترخيص
• ادعم هذا المشروع

صفحة التوثيق

• https://brumbelow.github.io/layerleak/docs

الموقع المنشور مبني من web/ على main بواسطة .github/workflows/pages.yml. مصدر التوثيق وعرض المتصفح المحاكي كلاهما موجود تحت هذا الدليل.

الإمكانيات الحالية:

• صور عامة من أي سجل متوافق مع OCI (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public، والسجلات المستضافة ذاتياً)
• فحص للقراءة فقط
• لا يوجد التحقق من الأسرار
• لا يتطلب الاعتماد على Daemon Docker
• فحص واعي بالمانيفست والطبقات
• يفحص نظام الملفات النهائي والقطع الأثرية للطبقات المحذوفة
• يفحص البيانات الوصفية لتكوين الصورة، ومتغيرات البيئة، والوسوم، والتاريخ
• يزيل التكرار للنتائج بناءً على بصمة السر ويجمع مقتطفات السياق المتطابقة المتكررة لكل مانيفست
• كاشفات أصلية لأكثر من 60 نوع سر بالإضافة إلى إعدادات TruffleHog الافتراضية كطبقة احتياطية
• يمنع نتائج مسارات الاختبار/الـ fixtures/الـ spec/الـ e2e/الـ acceptance لتقليل النتائج الإيجابية الكاذبة في صور التطوير

التثبيت

المتطلبات الأساسية:

• Go 1.25.7+

التثبيت باستخدام Go:

go install github.com/brumbelow/layerleak@latest
layerleak --help

الهدف القياسي للتثبيت هو جذر الوحدة. لتحديد إصدار معين بشكل صريح:

go install github.com/brumbelow/[email protected]

استبدل v1.0.0 بالعلامة v1.x.y المنشورة التي تريدها. تأكد من أن دليل GOBIN أو GOPATH/bin موجود في PATH.

مسار الوحدة هو github.com/brumbelow/layerleak، لذا فإن go install @latest يحل إلى أعلى علامة v1.x.y منشورة. يتطلب إصدار وحدة v2.x.y تغيير مسار الوحدة إلى github.com/brumbelow/layerleak/v2. الملفات الثنائية المثبتة كوحدة تُبلغ عن إصدار الوحدة المُحل عبر layerleak --version؛ البنيات من استنساخ محلي تُبلغ عن الإصدار الذي يُدمجه Go للاستنساخ، مع الرجوع إلى dev عندما لا يكون إصدار الوحدة متاحاً.

البناء من المصدر:

git clone https://github.com/brumbelow/layerleak.git
cd layerleak
go build -o layerleak .
./layerleak --help

تشغيل API باستخدام صورة حاوية:

docker pull ghcr.io/brumbelow/layerleak:latest
docker run --rm \
  -p 8080:8080 \
  -e LAYERLEAK_DATABASE_URL='postgres://<user>:<password>@<host>:5432/layerleak?sslmode=disable' \
  ghcr.io/brumbelow/layerleak:latest

صورة الحاوية تشغل API بشكل افتراضي وتضبط LAYERLEAK_API_ADDR=0.0.0.0:8080.

تكوين البيئة الاختياري:

cp .env.example .env

تكوين النتائج وقاعدة البيانات:

export LAYERLEAK_LOG_LEVEL=info
export LAYERLEAK_FINDINGS_DIR=findings
export LAYERLEAK_API_ADDR=127.0.0.1:8080
export LAYERLEAK_PERSIST_RAW_SECRETS=0
export LAYERLEAK_TAG_PAGE_SIZE=100
export LAYERLEAK_HTTP_TIMEOUT=30s
export LAYERLEAK_MAX_FILE_BYTES=1048576
export LAYERLEAK_MAX_LAYER_BYTES=536870912
export LAYERLEAK_MAX_LAYER_ENTRIES=50000
export LAYERLEAK_MAX_MANIFEST_BYTES=0
export LAYERLEAK_MAX_CONFIG_BYTES=0
export LAYERLEAK_MAX_TAG_RESPONSE_BYTES=8388608
export LAYERLEAK_MAX_REPOSITORY_TAGS=0
export LAYERLEAK_MAX_REPOSITORY_TARGETS=0
export LAYERLEAK_REGISTRY_REQUEST_ATTEMPTS=2
# تجاوزات السجل الاختيارية؛ عادةً تترك غير مضبوطة.
export LAYERLEAK_REGISTRY_BASE_URL=
export LAYERLEAK_REGISTRY_AUTH_URL=
export LAYERLEAK_DATABASE_URL=postgres://postgres:postgres@localhost:5432/layerleak?sslmode=disable

نفس المتغيرات وقيمها الافتراضية موجودة في .env.example، وهو المصدر الموثوق للقيم الافتراضية.

المتغير	القيمة الافتراضية	الغرض
LAYERLEAK_LOG_LEVEL	info	مستوى التسجيل: debug، info، warn، أو error.
LAYERLEAK_FINDINGS_DIR	غير مضبوط	أين يتم كتابة ملفات نتائج JSON. إذا كان غير مضبوط، الافتراضي هو findings/ تحت أقرب دليل أبوي يحتوي على go.mod، مع الرجوع إلى دليل العمل الحالي.
LAYERLEAK_API_ADDR	127.0.0.1:8080	عنوان الربط لخادم API. صورة الحاوية تتجاوز هذا إلى 0.0.0.0:8080.
LAYERLEAK_PERSIST_RAW_SECRETS	0	اضبط على 1 لكتابة قيم الأسرار الخام ومقتطفات السياق الخام إلى القرص وPostgres. النتائج تظل مخفية بشكل افتراضي.
LAYERLEAK_HTTP_TIMEOUT	30s	المهلة لكل طلب لكل استدعاء سجل (مانيفستات، بلوكات، صفحات علامات، رموز مصادقة). يقبل أي مدة Go (30s، 2m، 1h).
LAYERLEAK_MAX_FILE_BYTES	1048576 (1 MiB)	الحد الأقصى للبايتات المُفكوك ضغطها لكل ملف داخل طبقة. يتم تخطي الملفات الأكبر من ذلك باعتبارها كبيرة جداً. يجب أن يكون أكبر من الصفر.
LAYERLEAK_MAX_LAYER_BYTES	536870912 (512 MiB)	الحد الأقصى للبايتات في تيار الطبقة المُفكوك ضغطها لكل طبقة. 0 يعطل الحد.
LAYERLEAK_MAX_LAYER_ENTRIES	50000	الحد الأقصى لإدخالات tar لكل طبقة. 0 يعطل الحد.
LAYERLEAK_MAX_MANIFEST_BYTES	0	الحد الأقصى لبايتات جسم المانيفست. 0 يعطل الحد.
LAYERLEAK_MAX_CONFIG_BYTES	0	الحد الأقصى لبايتات جسم تكوين الصورة. 0 يعطل الحد.
LAYERLEAK_MAX_TAG_RESPONSE_BYTES	8388608 (8 MiB)	الحد الأقصى للبايتات لكل صفحة استجابة قائمة علامات السجل. 0 يعطل الحد.
LAYERLEAK_TAG_PAGE_SIZE	100	حجم صفحة قائمة علامات السجل للمسح على مستوى المستودع.
LAYERLEAK_MAX_REPOSITORY_TAGS	0	الحد الأقصى للعلامات التي يتم تعدادها لكل مسح مستودع. 0 يعطل الحد.
LAYERLEAK_MAX_REPOSITORY_TARGETS	0	الحد الأقصى للأهداف المميزة التي يتم حلها لكل مسح مستودع. 0 يعطل الحد.
LAYERLEAK_REGISTRY_REQUEST_ATTEMPTS	2	عدد المحاولات (بما في ذلك الأولى) لكل طلب سجل.
LAYERLEAK_REGISTRY_BASE_URL	غير مضبوط	تجاوز اختياري. عادةً يستنتج layerleak هذا من كل مرجع صورة؛ اضبط فقط لإجبار المسح عبر وكيل أو نقطة نهاية بديلة.
LAYERLEAK_REGISTRY_AUTH_URL	غير مضبوط	تجاوز اختياري. عادةً يتم اكتشافه من تحدي WWW-Authenticate الخاص بالسجل.
LAYERLEAK_DATABASE_URL	غير مضبوط	إذا تم ضبطه، يكتب layerleak المسوحات إلى Postgres ويفشل الأمر إذا لم ينجح التخزين الدائم.

عندما يتم ضبط أي من حدود MAX_* على قيمة موجبة، فإن تجاوزها يفشل المسح مع خطأ واضح بدلاً من قطع العمل بصمت.

سلوك النتائج:

• النتائج القابلة للتنفيذ تبقى في findings وتدفع حالة الخروج غير الصفرية للمسح.
• العناصر النائبة المحتملة للاختبار/المثال/العرض تنبعث بشكل منفصل كـ"نتائج مثال مكبوتة" ولا تُحتسب ضمن total_findings.
• سجلات النتائج تتضمن disposition و disposition_reason و line_number لتسهيل التصنيف ومراجعة النتائج الإيجابية الكاذبة.
• إذا تم تجاوز حد تشغيلي مُهيأ، لا يزال layerleak يكتب ويعرض النتائج الجزئية التي تم إنتاجها قبل الفشل، ثم يخرج بالحالة 1 لأن المسح غير مكتمل.

التخزين الدائم في Postgres

يأتي Layerleak مع ترحيلات SQL مُرقمة تحت migrations/. الترحيلات يدوية عن قصد. لا يقوم الماسح بإنشاء أو ترقية المخطط تلقائياً. يتطلب Layerleak خادم PostgreSQL >= 16.13 لـ API المدعوم بقاعدة البيانات واستمرارية الماسح.

طبق الترحيلات باستخدام psql بالترتيب:

psql "$LAYERLEAK_DATABASE_URL" -f migrations/0001_initial.up.sql
psql "$LAYERLEAK_DATABASE_URL" -f migrations/0002_finding_occurrence_metadata.up.sql
psql "$LAYERLEAK_DATABASE_URL" -f migrations/0003_scan_runs.up.sql

أو طبق الترحيلات باستخدام أمر المساعدة في الحاوية:

docker run --rm \
  -e LAYERLEAK_DATABASE_URL="$LAYERLEAK_DATABASE_URL" \
  ghcr.io/brumbelow/layerleak:latest \
  layerleak-migrate-up