layerleak

Layerleak는 읽기 전용 OCI 이미지 시크릿 스캐너입니다. Docker 데몬 없이 공개 이미지 참조를 해석하고, 다운로드한 콘텐츠를 OCI 다이제스트와 대조하여 검증하며, 레이어 상태를 재구성하고, 삭제된 아티팩트와 이미지 메타데이터를 검사한 뒤, 민감 정보가 제거되고 출처 정보가 풍부한 탐지 결과를 반환합니다.

Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public 및 기타 OCI 호환 레지스트리를 지원합니다. 결과는 JSON으로 저장할 수 있으며, 번들로 제공되는 API를 위해 PostgreSQL에 영구 저장할 수 있습니다.

• 문서
• OpenAPI 명세
• 변경 이력
• 보안 정책
• 기여 안내

이 개발 트리는 github.com/brumbelow/layerleak/v3 모듈 경로의 3.0.0 계열을 문서화합니다. 아래에 표시된 릴리스 후보 명령은 해당 태그가 정확히 게시된 후에만 설치할 수 있습니다. 변경 이력과 OpenAPI 문서의 3.0.0 레이블은 의도적으로 고정되어 있어, 승인된 릴리스 후보를 동일한 소스 커밋에서 승격할 수 있습니다.

보안 모델

Layerleak는 신뢰할 수 없는 이미지 콘텐츠를 스캔하므로, 기본값은 의도적으로 제한되어 있으며 실패 시 안전하게 닫힙니다(fail closed):

• 이미지, 매니페스트, 구성, 태그 응답, 파일, 레이어, 보존 상태 및 탐지 결과에 대한 제한이 있어 무한한 작업을 방지합니다;
• 매니페스트, 구성 및 레이어 본문은 사용 전에 공지된 OCI 다이제스트와 대조하여 검사됩니다;
• 리다이렉트는 횟수가 제한되고 재검증됩니다;
• 사설, 루프백, 링크 로컬 및 기타 비공개 레지스트리와 인증 대상은 해당 호스트가 명시적으로 허용되지 않는 한 차단됩니다;
• 탐지 결과, API 응답, 스캔 이력 및 로그는 기본적으로 민감 정보가 제거됩니다;
• 불완전한 커버리지는 partial 또는 failed로 보고되며, 결코 깨끗한 스캔으로 보고되지 않습니다.

Layerleak는 탐지된 자격 증명이 실제로 유효한지 검증하지 않습니다. API에는 권한 부여 모델이 없습니다. 즉 기본적으로 개방되어 있으며, 선택적으로 사용하는 LAYERLEAK_API_BEARER_TOKENS 공유 토큰 검사는 /api/ 경로에 대한 심층 방어일 뿐 접근 제어가 아닙니다. 어느 경우든 신뢰할 수 있는 네트워크나 인증된 게이트웨이 뒤에만 노출하십시오.

CLI 설치

Layerleak는 Go 1.27.1 이상이 필요합니다.```bash go install github.com/brumbelow/layerleak/v3@latest layerleak --version layerleak --help

`/v3` 모듈 경로가 표준 설치 대상이며, 설치되는 바이너리 이름은 여전히 `layerleak`입니다. 재현성이 중요할 때는 안정 버전이나 릴리스 후보를 명시적으로 고정하세요:```bash
go install github.com/brumbelow/layerleak/[email protected]
go install github.com/brumbelow/layerleak/[email protected]

/v3 경로의 @latest는 게시된 v3 릴리스 중 가장 높은 버전을 선택합니다. Go는 안정 버전이 존재하면 @latest에서 프리릴리스를 제외하므로, 릴리스 후보만 게시된 동안에는 @latest가 최신 후보로 해석됩니다. /v3 없이 루트 경로 github.com/brumbelow/layerleak를 사용하면 영원히 v1.0.0에 머무릅니다. 항상 /v3를 포함하세요. 체크아웃 빌드는 더티 워크트리 마커를 포함한 VCS 기반 개발 버전을 보고하거나, VCS 정보가 없으면 dev를 보고합니다. 릴리스 설치 바이너리는 layerleak --version을 통해 해석된 모듈 버전을 보고합니다.

릴리스 아카이브 다운로드

모든 릴리스에는 미리 빌드된 CLI 아카이브도 첨부되므로 Go 툴체인이 필요하지 않습니다. linux와 darwin의 amd64 및 arm64용 layerleak_<version>_<os>_<arch>.tar.gz(layerleak, LICENSE, THIRD_PARTY_NOTICES.md 포함)와 layerleak_<version>_windows_amd64.zip(layerleak.exe)이 제공됩니다. 각 릴리스에는 릴리스 워크플로가 키리스 방식으로 서명한 layerleak_<version>_checksums.txt(layerleak_<version>_checksums.txt.sigstore.json)와 모든 아카이브에 대한 빌드 출처 증명이 포함됩니다. 실행하기 전에 검증하세요:```bash version=v3.0.0 archive="layerleak_${version}linux_amd64.tar.gz" checksums="layerleak${version}_checksums.txt" base="https://github.com/brumbelow/layerleak/releases/download/${version}" curl --fail --location --proto '=https' --tlsv1.2 --remote-name-all
"${base}/${archive}" "${base}/${checksums}" "${base}/${checksums}.sigstore.json"

sha256sum --check --ignore-missing "${checksums}" cosign verify-blob
--bundle "${checksums}.sigstore.json"
--certificate-identity 'https://github.com/Brumbelow/layerleak/.github/workflows/container-release.yml@refs/heads/main'
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com'
"${checksums}" gh attestation verify "${archive}" --repo Brumbelow/layerleak
--signer-workflow Brumbelow/layerleak/.github/workflows/container-release.yml
--source-ref refs/heads/main --deny-self-hosted-runners

tar -xzf "${archive}" layerleak ./layerleak version

서명은 체크섬 파일이 `main`의 이 저장소 릴리스 워크플로에서 왔음을 증명하고, 체크섬은 아카이브를 그 파일에 결속하며, 증명은 아카이브를 이를 빌드한 워크플로 실행에 독립적으로 결속합니다. 릴리스의 `release-manifest.json`은 모든 아카이브와 그 안에 든 바이너리의 다이제스트를 나열합니다. 안정 릴리스는 승인된 릴리스 후보의 커밋을 안정 버전 문자열로 다시 빌드하고, 재빌드가 후보의 바이너리를 바이트 단위로 재현하지 못하면 게시를 거부하므로, `layerleak version`은 다운로드한 태그를 정확히 보고합니다.

### GitHub Action

저장소 루트는 러너용 아카이브를 다운로드하고, 위와 같이 검증하며(체크섬, `scripts/release-tools.sh`에 고정된 cosign 릴리스와 함께 제공되는 체크섬 파일의 cosign 번들, 그리고 아카이브 증명), `layerleak scan`을 실행하는 복합 액션입니다. 릴리스 태그에 고정하세요. 일치하는 아카이브는 해당 릴리스에서 다운로드됩니다:```yaml
name: Image secrets
on: { push: { branches: [main] } }
permissions: { contents: read, security-events: write }
jobs:
  layerleak:
    runs-on: ubuntu-24.04
    steps:
      - id: scan
        uses: brumbelow/[email protected]
        with: { image: "ghcr.io/${{ github.repository }}:${{ github.sha }}", fail-on: none }
      - uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
        if: ${{ always() && steps.scan.outputs.sarif-file != '' }}
        with: { sarif_file: "${{ steps.scan.outputs.sarif-file }}" }

Input	Default	Meaning
image	required	스캔할 이미지 참조; 프라이빗 레지스트리는 스텝 env에서 LAYERLEAK_REGISTRY_USERNAME/LAYERLEAK_REGISTRY_PASSWORD를 사용합니다.
version	uses:의 태그	아카이브가 다운로드되는 릴리스; uses:가 브랜치나 커밋을 가리킬 때만 설정합니다.
format	sarif	summary, json 또는 sarif.
fail-on	low	--fail-on에 전달됨; none은 스텝을 실패시키지 않고 보고합니다.
allow-partial	false	--allow-partial을 전달합니다.
platform	모든 linux 매니페스트	--platform에 전달됩니다.
output-file	$RUNNER_TEMP/layerleak/results.<ext>	포맷된 결과가 기록되는 위치.
extra-args	비어 있음	추가 layerleak scan 플래그로, 공백으로 분할되어 마지막에 추가됩니다 (예: --all-tags --max-repository-tags 50).

Outputs: exit-code (CLI 종료 코드, "Scan images" 아래의 표 참조), result-file (기록된 파일), sarif-file (format이 sarif일 때 동일한 경로, 그렇지 않으면 비어 있음) 그리고 version (다운로드되고 검증된 릴리스). 이 스텝은 CLI가 0이 아닌 값으로 종료될 때 정확히 실패하므로, fail-on: none과 업로드 스텝의 if: always()를 함께 사용하면 보고 전용 스캔이 됩니다. 이 액션은 절대 발견 사항을 출력하지 않으며, 수정된 summary 포맷만 로그에 에코되고, 스캔은 --no-artifacts로 실행됩니다. curl, tar (또는 Windows에서는 unzip/7z) 그리고 GitHub CLI가 필요하며, 이들은 모두 GitHub 호스팅 Linux, macOS 및 Windows 러너에 존재합니다.

소스에서 빌드:```bash git clone https://github.com/brumbelow/layerleak.git cd layerleak go build -o layerleak . ./layerleak --help

지원되는 배포 경로는 CLI의 경우 위의 `/v3` 모듈 경로이고, API와 그에 번들된 마이그레이션, purge, healthcheck 명령의 경우 `ghcr.io/brumbelow/layerleak:<published-version>`입니다. `cmd/*` 패키지는 개발용 소스 빌드 대상이며, 별도로 버전이 지정된 설치 경로가 아닙니다. PostgreSQL 기반 API 버전을 시작하기 전에, 그에 맞는 `layerleak-migrate-up` 바이너리나 컨테이너 엔트리포인트를 실행하고 마이그레이션이 성공할 때까지 기다리십시오. API는 설치된 스키마가 정확히 기대하는 버전이 아니면 시작을 거부하며, 시작 후에는 `/readyz`가 매 프로브마다 데이터베이스와 스키마를 다시 확인하므로 이후의 성능 저하도 보고됩니다.

## 플랫폼 지원

| 구성 요소 | 플랫폼 | 검증 방법 |
| --- | --- | --- |
| `layerleak` CLI | `go install`을 통한 Linux, macOS, Windows의 amd64 및 arm64 | CI에서 linux/amd64로 테스트를 실행하며, darwin/arm64, darwin/amd64, windows/amd64, linux/arm64는 모든 변경 시 컴파일 및 검증됩니다. |
| API 이미지 | `linux/amd64`, `linux/arm64` | 릴리스 워크플로가 두 플랫폼 모두에 대해 빌드, 스모크 테스트, 스캔, 서명을 수행합니다. |

Windows에서는 동적 진행 표시가 콘솔을 가상 터미널 모드로 전환합니다. 이를 거부하는 콘솔(Windows 10 1511 이전)은 일반 진행 라인으로 폴백하며, `--progress plain`도 마찬가지입니다. bash, zsh, fish, PowerShell용 셸 완성은 `layerleak completion <shell>`에서 제공됩니다.

CLI는 HTTPS를 통해 또는 `HTTPS_PROXY`를 통해 레지스트리에 직접 접근합니다([Configuration](#configuration) 참조). API는 일반 HTTP로 수신 대기하며, 배포 환경이 TLS를 종료하고 클라이언트를 인증하며 속도 제한을 적용할 것으로 기대합니다. [SECURITY.md](https://github.com/brumbelow/layerleak/blob/main/SECURITY.md#security-boundaries)를 참조하십시오.

## 이미지 스캔