layerleak OCI इमेज सीक्रेट स्कैनर

CONTRIBUTING.md में योगदान दिशानिर्देश देखें।

• OCI इमेज सीक्रेट स्कैनर जो किसी भी सार्वजनिक OCI-अनुरूप रजिस्ट्री (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public, स्व-होस्टेड) के विरुद्ध काम करता है। यह इमेज लेयर, कॉन्फ़िग मेटाडेटा और इमेज हिस्ट्री का विश्लेषण करता है, फिर मैनिफ़ेस्ट डाइजेस्ट द्वारा डीडुप्लिकेट किए गए निष्कर्ष संग्रहीत करता है।
• पारंपरिक सीक्रेट स्कैनर अक्सर कंटेनर इमेज को एक फ्लैट ब्लॉब के रूप में मानते हैं या स्थानीय Docker डेमॉन पर निर्भर होते हैं। यह प्रोजेक्ट OCI इमेज इंटरनल के आसपास डिज़ाइन किया गया है

सामग्री

• दस्तावेज़ पृष्ठ
• वर्तमान क्षमताएँ
• स्थापना
• Postgres दृढ़ता
• शुरू कैसे करें
• HTTP API
• 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, स्व-होस्टेड) से सार्वजनिक इमेज
• केवल-पढ़ने के लिए स्कैनिंग
• कोई सीक्रेट सत्यापन नहीं
• कोई Docker डेमॉन निर्भरता आवश्यक नहीं
• मैनिफ़ेस्ट-जागरूक और लेयर-जागरूक स्कैनिंग
• अंतिम फ़ाइलसिस्टम और हटाए गए-लेयर आर्टिफैक्ट्स को स्कैन करता है
• इमेज कॉन्फ़िग मेटाडेटा, env vars, लेबल और हिस्ट्री स्कैन करता है
• सीक्रेट फिंगरप्रिंट द्वारा निष्कर्षों को डीडुप्लिकेट करता है और प्रति मैनिफ़ेस्ट दोहराए गए समान संदर्भ स्निपेट्स को संक्षिप्त करता है
• 60+ सीक्रेट प्रकारों के लिए मूल डिटेक्टर और फ़ॉलबैक लेयर के रूप में TruffleHog डिफ़ॉल्ट
• विकास इमेज में झूठी सकारात्मकताओं को कम करने के लिए test/fixture/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.x.y टैग से v1.0.0 बदलें। सुनिश्चित करें कि आपका 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
# Optional registry overrides; usually leave unset.
export LAYERLEAK_REGISTRY_BASE_URL=
export LAYERLEAK_REGISTRY_AUTH_URL=
export LAYERLEAK_DATABASE_URL=postgres://postgres:postgres@localhost:5432/layerleak?sslmode=disable

यही चर और उनके डिफ़ॉल्ट .env.example में रहते हैं, जो डिफ़ॉल्ट मानों का स्रोत है।

जब कोई MAX_* सीमा सकारात्मक मान पर सेट की जाती है, तो उसे पार करने पर स्कैन स्पष्ट त्रुटि के साथ विफल हो जाता है, बजाय चुपचाप कार्य को काटने के।

परिणाम व्यवहार:

• कार्रवाई योग्य निष्कर्ष findings में रहते हैं और गैर-शून्य स्कैन निकास स्थिति चलाते हैं।
• संभावित test/example/demo प्लेसहोल्डर को दबाए गए उदाहरण निष्कर्ष के रूप में अलग से उत्सर्जित किया जाता है और total_findings में नहीं गिना जाता है।
• निष्कर्ष रिकॉर्ड में disposition, disposition_reason, और line_number शामिल हैं ताकि ट्राइएज और झूठी-सकारात्मक समीक्षा आसान हो सके।
• यदि एक कॉन्फ़िगर की गई परिचालन सीमा पार हो जाती है, तो layerleak अभी भी विफलता से पहले उत्पन्न आंशिक परिणामों को लिखता और प्रस्तुत करता है, फिर स्थिति 1 के साथ बाहर निकलता है क्योंकि स्कैन अधूरा है।

Postgres दृढ़ता

Layerleak migrations/ के अंतर्गत संस्करणित SQL माइग्रेशन भेजता है। माइग्रेशन जानबूझकर मैनुअल हैं। स्कैनर स्वचालित रूप से स्कीमा नहीं बनाता या अपग्रेड नहीं करता। Layerleak को DB-समर्थित API और स्कैनर दृढ़ता के लिए PostgreSQL सर्वर >= 16.13 की आवश्यकता है।

माइग्रेशन को क्रम में 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

जब माइग्रेशन पहले से लागू होते हैं तो layerleak-migrate-up को फिर से चलाना सुरक्षित है। यदि यह आंशिक माइग्रेशन स्थिति का पता लगाता है, तो यह गैर-शून्य निकास करता है और मैनुअल हस्तक्षेप के लिए पूछता है। हेल्पर सर्वर संस्करण >= 16.13 को भी लागू करता है और मान्य करता है कि बंडल postgresql-client-16 Ubuntu PGDG 24.04 पैकेजिंग (.pgdg24.04+) का उपयोग संस्करण >= 16.13-1.pgdg24.04+1 पर करता है।

माइग्रेशन को उल्टे क्रम में वापस रोल करें:

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

परिचालन डिफ़ॉल्ट:

• माइग्रेशन से योगात्मक रहने की उम्मीद है।
• स्कीमा first_seen_at और last_seen_at के साथ वर्तमान डीडुप्लिकेट स्थिति रखता है, और scan_runs में केवल-जोड़ स्कैन हिस्ट्री भी संग्रहीत करता है।
• वर्तमान स्कैन द्वारा छूए गए टैग के लिए टैग मैपिंग ताज़ा की जाती है।
• निष्कर्ष (manifest_digest, fingerprint) द्वारा विहित रूप से डीडुप्लिकेट किए जाते हैं, और दृढ़ता से पहले दोहराए गए समान संदर्भ स्निपेट्स को संक्षिप्त किया जाता है।
• स्कैन हिस्ट्री सार्वजनिक परिणाम JSON का एक संपादित स्नैपशॉट संग्रहीत करती है, कच्चे मान या कच्चे स्निपेट नहीं।

गुप्त-सुरक्षा नोट:

• Postgres दृढ़ता डिफ़ॉल्ट रूप से संपादित पूर्वावलोकन संग्रहीत करती है।
• यदि LAYERLEAK_PERSIST_RAW_SECRETS=1, तो Postgres कच्चे निष्कर्ष मान और कच्चे स्निपेट भी संग्रहीत करता है।
• scan_runs.result_json स्नैपशॉट संपादित रहता है।
• layerleak के लिए एक समर्पित डेटाबेस या स्कीमा का उपयोग करें।
• सबसे सुरक्षित शुद्धिकरण पथ के लिए, व्यक्तिगत पंक्तियों को शल्य चिकित्सा से हटाने का प्रयास करने के बजाय समर्पित डेटाबेस या स्कीमा को हटा दें।

शुरू कैसे करें

CLI सहायता दिखाएँ:

layerleak --help
layerleak scan --help

किसी भी समर्थित रजिस्ट्री पर एक सार्वजनिक OCI इमेज के विरुद्ध स्कैन चलाएँ:

./layerleak scan ubuntu
./layerleak scan library/nginx:latest --format json
./layerleak scan alpine:latest --platform linux/amd64
./layerleak scan mongo
./layerleak scan ghcr.io/homebrew/core/hello:latest
./layerleak scan quay.io/prometheus/busybox:latest
./layerleak scan gcr.io/distroless/static:nonroot
./layerleak scan public.ecr.aws/docker/library/alpine:3.20
./layerleak scan mcr.microsoft.com/hello-world:latest

प्रत्येक स्कैन findings आउटपुट निर्देशिका में एक JSON निष्कर्ष फ़ाइल लिखता है। यदि LAYERLEAK_FINDINGS_DIR सेट नहीं है, तो डिफ़ॉल्ट आउटपुट निर्देशिका go.mod वाली निकटतम मूल निर्देशिका (आमतौर पर रेपो रूट) के अंतर्गत findings/ है, जब कोई रेपो रूट नहीं मिलता है तो वर्तमान कार्यशील निर्देशिका पर वापस आ जाता है।

वे सहेजी गई निष्कर्ष फ़ाइलों में प्रत्येक निष्कर्ष के लिए redacted_value, संपादित context_snippet, सटीक स्रोत स्थान, विस्थापन मेटाडेटा और लाइन नंबर वाले निष्कर्ष रिकॉर्ड होते हैं। यदि LAYERLEAK_PERSIST_RAW_SECRETS=1, तो सहेजी गई निष्कर्ष फ़ाइलों में कच्चा value और raw_context_snippet भी शामिल होता है। यदि Postgres दृढ़ता सक्षम है, तो कच्चा findings.value और finding_occurrences.raw_snippet खाली रहता है जब तक कि LAYERLEAK_PERSIST_RAW_SECRETS=1 न हो। मल्टी-आर्क इमेज के लिए, layerleak उन्हें असफल प्लेटफ़ॉर्म स्कैन के रूप में गिनने के बजाय application/vnd.in-toto+json जैसे प्रमाणन और उत्पत्ति मैनिफ़ेस्ट को छोड़ देता है।

नंगे रिपॉजिटरी स्वीप:

• mongo जैसा नंगे रेपो नाम पास करने से उस रेपो में प्रत्येक सार्वजनिक टैग की गणना होती है, प्रत्येक टैग को डाइजेस्ट में हल करता है, डुप्लिकेट डाइजेस्ट को समूहित करता है, और अलग-अलग लक्ष्यों को स्कैन करता है।
• layerleak स्वीप शुरू करने से पहले stderr पर एक चेतावनी प्रिंट करता है ताकि CI लॉग और ऑटोमेशन आउटपुट में दायरा स्पष्ट हो।
• यदि आप केवल एक एकल इमेज चाहते हैं, तो एक स्पष्ट टैग या डाइजेस्ट जैसे mongo:latest या mongo@sha256:... पास करें।

कमांड सिंटैक्स:

layerleak [command]
layerleak scan <image-ref> [flags]

रिपॉजिटरी स्वीप के लिए स्कोप फ़्लैग (प्रत्येक एकल कमांड के लिए मिलान पर्यावरण चर को ओवरराइड करता है):

HTTP API

Layerleak cmd/api के अंतर्गत एक न्यूनतम JSON API भी भेजता है। API Postgres-समर्थित है और LAYERLEAK_DATABASE_URL की आवश्यकता है; यह डिस्क पर findings फ़ाइलों से सेवा नहीं करता है।

इसे इसके साथ शुरू करें:

go run ./cmd/api

या API कंटेनर चलाएँ:

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

वर्तमान एंडपॉइंट:

• GET /health
• POST /api/v1/scans
• GET /api/v1/scans/{id}
• GET /api/v1/repositories
• GET /api/v1/repositories/{repository}/scans
• GET /api/v1/repositories/{repository}/findings
• GET /api/v1/findings/{id}

GET /health {"status":"ok"} लौटाता है और इसे कॉन्फ़िगर किए गए स्टोर या स्कैनर की आवश्यकता नहीं है। यह Kubernetes रेडीनेस प्रोब और Docker Compose healthcheck लक्ष्यों के लिए उपयुक्त है।

POST /api/v1/scans सिंक्रोनस रहता है। यह reference और वैकल्पिक platform के साथ एक JSON बॉडी स्वीकार करता है, और जब भी Postgres दृढ़ता सक्षम होती है तो scan_run_id लौटाता है। API स्कैन प्रतिक्रियाएं CLI JSON आउटपुट के समान संपादित परिणाम स्कीमा का पुन: उपयोग करती हैं। GET /api/v1/scans/{id} बने रहे रन मेटाडेटा और संग्रहीत संपादित परिणाम स्नैपशॉट लौटाता है। रिपॉजिटरी और निष्कर्ष एंडपॉइंट भी संपादित रहते हैं: वे redacted_value और संपादित context_snippet लौटाते हैं, Postgres से कच्चे सीक्रेट मान या कच्चे स्निपेट कभी नहीं।

GET /api/v1/repositories/{repository}/scans और GET /api/v1/repositories/{repository}/findings एक वैकल्पिक registry क्वेरी पैरामीटर स्वीकार करते हैं (उदाहरण के लिए ?registry=ghcr.io)। जब छोड़ा जाता है, तो रजिस्ट्री पिछड़ी संगतता के लिए डिफ़ॉल्ट रूप से docker.io होती है। GHCR, Quay, GCR, MCR, Amazon ECR Public, या किसी स्व-होस्टेड रजिस्ट्री पर रिपॉजिटरी के स्कैन लाने के लिए इसका उपयोग करें।

सूची एंडपॉइंट (/repositories, /repositories/{repository}/scans, /repositories/{repository}/findings) पेजिनेशन के लिए ?limit= और ?offset= स्वीकार करते हैं। limit डिफ़ॉल्ट रूप से 50 है और 200 पर सीमित है। /repositories/{repository}/findings भी ?disposition=actionable|suppressed|all स्वीकार करता है; जब छोड़ा जाता है तो प्रतिक्रिया में केवल कार्रवाई योग्य निष्कर्ष शामिल होते हैं।

API में प्रमाणीकरण शामिल नहीं है। संगठन तैनाती के लिए, इसे एक निजी नेटवर्क पर रखें और इसे अपने स्वयं के authn/authz गेटवे या रिवर्स प्रॉक्सी नीति के साथ फ्रंट करें।

Docker Compose तैनाती (Dockge / Komodo)

यह रेपो docker-compose.yml में db, migrate, और api सेवाओं के साथ एक Compose स्टैक भेजता है। db सेवा बेसलाइन postgres:16.13-alpine पर पिन की गई है। यदि आप एक अलग Postgres इमेज का उपयोग करते हैं, तो सर्वर संस्करण 16.13 या नया रखें।

तैनाती चर सेट करें (शेल में निर्यात करें या docker-compose.yml के बगल में .env फ़ाइल में रखें):

export LAYERLEAK_IMAGE=ghcr.io/brumbelow/layerleak:latest
export LAYERLEAK_DB_NAME=layerleak
export LAYERLEAK_DB_USER=layerleak
export LAYERLEAK_DB_PASSWORD=replace-me
export LAYERLEAK_API_PORT=8080

तैनाती से पहले प्रस्तुत Compose कॉन्फ़िगरेशन को मान्य करें:

docker compose config

API शुरू करने से पहले एक बार माइग्रेशन चलाएँ:

docker compose --profile manual run --rm migrate

API सेवा शुरू करें:

docker compose up -d api

Dockge या Komodo में, उसी Compose फ़ाइल को आयात करें और लंबे समय तक चलने वाली api सेवा को सक्षम करने से पहले एक बार migrate सेवा चलाएँ।

लाइसेंस

MIT लाइसेंस के तहत जारी — LICENSE देखें।

इस प्रोजेक्ट का समर्थन करें