cr0hn/dockerscan가장 포괄적인 Docker 보안 스캐너
<div align="center">
<img src="https://assets.kitploit.com/production/public/readmes/1309/3345979faae1cdabbe2912dfcaf46221df5cb53697630a8e8dcc5eebf814e949.png" alt="DockerScan 로고" width="200">
# DockerScan v2.0
### *가장 포괄적인 Docker 보안 스캐너*
[](LICENSE)
[](https://golang.org/)
[](https://github.com/cr0hn/dockerscan/releases)
[](https://github.com/cr0hn/dockerscan/actions/workflows/dockerscan.yml)
[](https://github.com/cr0hn/dockerscan)
[](https://goreportcard.com/report/github.com/cr0hn/dockerscan)
[](https://github.com/cr0hn/dockerscan/releases)
**작성자: [Daniel Garcia (cr0hn)](https://cr0hn.com)** | [GitHub](https://github.com/cr0hn/dockerscan) | [웹사이트](https://cr0hn.com)
---
[기능](#-기능) •
[설치](#-설치) •
[빠른 시작](#-빠른-시작) •
[문서](#-문서) •
[사용 사례](#-사용-사례) •
[새로운 기능](#-v20의-새로운-기능) •
[기여하기](#-기여하기)
</div>
---
## 📑 목차
- [개요](#-개요)
- [기능](#-기능)
- [v2.0의 새로운 기능](#-v20의-새로운-기능)
- [설치](#-설치)
- [빠른 시작](#-빠른-시작)
- [사용법](#-사용법)
- [프라이빗 레지스트리 인증](#-프라이빗-레지스트리-인증)
- [보안 스캐너](#-보안-스캐너)
- [출력 형식](#-출력-형식)
- [사용 사례](#-사용-사례)
- [비교](#-다른-도구와의-비교)
- [아키텍처](#-아키텍처)
- [기여하기](#-기여하기)
- [참고 자료](#-참고-자료)
- [라이선스](#-라이선스)
- [저자](#-저자)
---
## 🎯 개요
**DockerScan v2.0**은 Go로 완전히 다시 작성된 차세대 Docker 컨테이너 및 이미지 보안 스캐너입니다. 최신 2024-2025 연구, 업계 표준(CIS Benchmark, NIST SP 800-190), 그리고 프로덕션 환경에서 발견된 실제 공격 패턴을 기반으로 여러 보안 스캐닝 기술을 결합합니다.
### DockerScan v2.0을 선택해야 하는 이유는?
- ✅ **가장 포괄적**: 하나의 도구에 5개 이상의 보안 스캐닝 기술 결합
- ✅ **최신 연구**: 2024-2025 공급망 공격 및 CVE 기반
- ✅ **프로덕션 준비 완료**: CI/CD를 위한 SARIF 출력, 자동화를 위한 종료 코드
- ✅ **번개처럼 빠름**: Go로 작성되어 동시 스캐닝 지원
- ✅ **확장 가능**: 사용자 정의 스캐너를 위한 플러그인 아키텍처
- ✅ **무료 및 오픈 소스**: BSD-3 라이선스
---
## 🌟 기능
### 🛡️ **보안 스캐닝 모듈**
#### 1. **CIS Docker Benchmark v1.7.0**
80개 이상의 자동화된 제어 항목을 통한 완전한 규정 준수 검사:
- ✅ 호스트 구성 보안 (13개 검사)
- ✅ Docker 데몬 강화 (18개 검사)
- ✅ 파일 및 디렉터리 권한 (9개 검사)
- ✅ 컨테이너 이미지 모범 사례 (13개 검사)
- ✅ 런타임 보안 검증 (31개 이상 검사)
- ✅ 보안 운영 규정 준수
#### 2. **공급망 공격 탐지** 🆕
2024년 실제 공격 캠페인 기반:
- ✅ **이미지 없는 컨테이너 탐지** - 실제 레이어가 없는 악성 컨테이너 식별 (Docker Hub에서 400만 개 이상 발견)
- ✅ **암호화폐 채굴기 탐지** - 채굴 악성 코드 탐지 (12만 개 이상의 악성 이미지 풀 감지)
- ✅ **백도어 라이브러리 탐지** - 손상된 종속성 포착 (xz-utils, liblzma 사고)
- ✅ **이미지 서명 검증** - Notary/Cosign을 사용한 서명 검증
- ✅ **피싱 콘텐츠 탐지** - 사회 공학을 위한 문서 스캔
- ✅ **악성 네트워크 대상** - C2 서버, 채굴 풀, Tor 노드 식별
#### 3. **고급 시크릿 탐지** 🔑
최신 API(2024 업데이트)를 포함한 40개 이상의 시크릿 패턴:
- ✅ **클라우드 제공업체**: AWS, GCP, Azure 자격 증명
- ✅ **버전 관리**: GitHub, GitLab, Bitbucket 토큰
- ✅ **AI/ML API**: OpenAI, Anthropic, Hugging Face 키
- ✅ **결제**: Stripe, PayPal, Square 키
- ✅ **커뮤니케이션**: Slack, SendGrid, Twilio, Mailchimp
- ✅ **인증**: JWT 토큰, OAuth 토큰
- ✅ **암호화**: 개인 키 (RSA, SSH, PGP, EC, DSA), 인증서
- ✅ **데이터베이스**: PostgreSQL, MySQL, MongoDB 연결 문자열
- ✅ **Docker**: 레지스트리 인증 토큰
- ✅ **엔트로피 분석**: 알려지지 않은 시크릿에 대한 Shannon 엔트로피 계산 (임계값 >4.5)
#### 4. **CVE 및 취약점 스캐닝** 🚨
2024-2025 주요 CVE 탐지:
- ✅ **CVE-2024-21626** - runc 컨테이너 탈출 (CVSS 8.6)
- ✅ **CVE-2024-23651** - BuildKit 캐시 중독 RCE (CVSS 9.1)
- ✅ **CVE-2024-23652** - BuildKit 경쟁 조건 (CVSS 7.5)
- ✅ **CVE-2024-23653** - BuildKit 권한 상승
- ✅ **CVE-2024-8695/8696** - Docker Desktop RCE (CVSS 8.8)
- ✅ **CVE-2025-9074** - Docker Desktop 로컬 액세스 취약점
- ✅ 수명 종료 기본 이미지 탐지
- ✅ 알려진 취약 패키지 스캐닝
#### 5. **런타임 보안 분석** ⚙️
컨테이너 런타임 강화 검사:
- ✅ **Linux Capabilities 감사** - 위험한 능력 탐지 (CAP_SYS_ADMIN, CAP_NET_ADMIN 등)
- ✅ **Seccomp 프로필 검증** - 시스템 호출 필터링 활성화 확인
- ✅ **AppArmor/SELinux 검사** - 강제 접근 제어 검증
- ✅ **권한 있는 컨테이너 탐지** - 전체 호스트 접근 권한이 있는 컨테이너 식별
- ✅ **네임스페이스 격리** - PID, IPC, 네트워크, 사용자 네임스페이스 검사
- ✅ **컨테이너 탈출 징후** - 일반적인 탈출 기술 탐지
### 📊 **보고 및 통합**
- **JSON** - 자동화를 위한 기계 판독 가능 출력
- **SARIF** - 다음과의 기본 통합:
- GitHub 보안 탭
- Azure DevOps
- VS Code 확장
- GitLab 보안 대시보드
- **아름다운 CLI** - 이모지가 포함된 색상 코드 심각도 수준
- **종료 코드** - CI/CD 친화적 (0=깨끗함, 1=경고, 2=심각)
### 🚀 **성능**
- ⚡ **Python 대안보다 10배 빠름**
- 🔄 **Go 고루틴을 사용한 동시 스캐닝**
- 💾 **낮은 메모리** 사용량 (~50-100MB)
- 📦 **단일 바이너리** - 종속성 없음
---
## 🆕 v2.0의 새로운 기능?
DockerScan v2.0은 **완전히 처음부터 다시 작성된** 버전입니다. v1.x에서 변경된 사항은 다음과 같습니다:
### 주요 변경 사항
| 기능 | v1.x (Python) | v2.0 (Go) |
|------|--------------|-----------|
| **언어** | Python 3.5+ | Go 1.21+ |
| **성능** | ~500 이미지/시간 | ~5000 이미지/시간 |
| **메모리 사용량** | 200-500 MB | 50-100 MB |
| **배포** | pip install + 종속성 | 단일 바이너리 |
| **보안 스캐너** | 2개 모듈 | 5개 모듈 |
| **CIS Benchmark** | 부분 지원 | 전체 v1.7.0 (80개 이상 검사) |
| **공급망** | ❌ 사용 불가 | ✅ 2024 연구 기반 |
| **시크릿 패턴** | 10개 패턴 | 40개 이상 패턴 |
| **CVE 탐지** | 기본 | 2024-2025 CVE |
| **런타임 보안** | ❌ 사용 불가 | ✅ 전체 능력 감사 |
| **SARIF 출력** | ❌ 사용 불가 | ✅ 완전 지원 |
| **CI/CD 통합** | 수동 | 네이티브 (종료 코드, SARIF) |
### v1.x에서 유지된 기능
- ✅ **공격 도구** - 이미지 트로이목마화 기능 (v2.1에서 곧 제공)
- ✅ **레지스트리 작업** - Push, Pull, 삭제 작업 (v2.1에서 곧 제공)
- ✅ **네트워크 스캐닝** - Docker 레지스트리 검색 (v2.1에서 곧 제공)
### v2.0.5 새로운 기능 🔐
- 🔑 **프라이빗 레지스트리 인증** - 프라이빗 레지스트리 이미지 스캔 완전 지원 (#24 수정)
- 🌐 **멀티 레지스트리 지원** - Docker Hub, GHCR, ECR, GCR, ACR, GitLab 및 자체 호스팅 레지스트리
- 🔐 **다양한 인증 방법** - 환경 변수 (CI/CD), CLI 플래그 (테스트), Docker 설정 파일 (원활함)
- 🎯 **스마트 인증 우선순위** - CLI 플래그 > ENV 변수 > Docker 설정 (자동 선택)
- 📝 **향상된 오류 메시지** - 레지스트리별 힌트 (ECR 토큰 만료, 속도 제한, 인증서)
- 🧪 **포괄적인 테스트** - 64개 테스트 케이스, 91.2% 커버리지, 실제 프라이빗 레지스트리로 테스트 완료
- 📚 **완전한 문서** - 모든 주요 클라우드 레지스트리 및 인증 방법 예제 포함
### v2.0.4 새로운 기능
- 🗄️ **CVE 데이터베이스 통합** - NVD 데이터를 포함한 로컬 SQLite 데이터베이스 (2.5년 분량의 CVE)
- 🔄 **매일 자동 업데이트** - GitHub Action이 매일 CVE 데이터베이스 업데이트
- ⚡ **병렬 CVE 다운로드** - 더 빠른 데이터베이스 생성을 위한 4개 워커 (nvd2sqlite)
- 🔁 **백오프 재시도** - 속도 제한된 NVD API 요청에 대한 자동 재시도
- 📦 **`--from-file` 플래그** - 로컬 파일에서 CVE 데이터베이스 설치 (오프라인/에어갭 환경)
- 🔇 **자동 모드 (`-q`)** - CI/CD 파이프라인을 위한 배너 출력 억제
- 🧹 **거짓 긍정 감소** - 엔트로피 필터링으로 시크릿 탐지 개선
### 재작성 이유
1. **성능** - Go는 고루틴을 통해 10배 빠른 스캐닝 제공
2. **최신 위협** - 2024-2025 공격 패턴 통합
3. **엔터프라이즈 준비** - SARIF 출력, 종료 코드, 단일 바이너리 배포
4. **확장성** - 사용자 정의 스캐너를 위한 깔끔한 플러그인 아키텍처
5. **유지보수성** - 타입 안전성, 더 나은 오류 처리, 기여 용이성
---
## 📦 설치
### 옵션 1: 사전 빌드된 바이너리 다운로드 (권장)
사전 컴파일된 바이너리는 모든 버전 태그에 대해 GitHub Actions를 통해 자동으로 빌드 및 릴리스됩니다.
**지원 플랫폼:**
- **Linux**: amd64, arm64, 386
- **macOS**: amd64 (Intel), arm64 (Apple Silicon)
- **Windows**: amd64, arm64, 386
- **FreeBSD**: amd64
#### Linux (amd64)```bash
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/
```
#### Linux (arm64)```bash
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-arm64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/
```
#### macOS (Intel)```bash
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-darwin-amd64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/
```
#### macOS (Apple Silicon)```bash
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-darwin-arm64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/
```
#### 윈도우 (PowerShell)```powershell
Invoke-WebRequest -Uri "https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-windows-amd64.exe" -OutFile "dockerscan.exe"
```
#### 다운로드 확인 (선택 사항이지만 권장됨)```bash
# Download checksums
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/checksums.txt -o checksums.txt
# Verify (Linux/macOS)
sha256sum -c checksums.txt --ignore-missing
```
### 옵션 2: 소스에서 빌드```bash
# Clone repository
git clone https://github.com/cr0hn/dockerscan
cd dockerscan/dockerscan-v2
# Build
make build
# Install
sudo make install
# Or build manually
go build -o bin/dockerscan ./cmd/dockerscan
```
### 옵션 3: Go Install```bash
go install github.com/cr0hn/dockerscan/v2/cmd/dockerscan@latest
```
---
## 🚀 빠른 시작
### 첫 번째 설정
스캔하기 전에 CVE 데이터베이스를 다운로드하세요 (매일 업데이트, ~30MB 압축):```bash
# Download latest CVE database from GitHub
dockerscan update-db
```
> **Tip**: 데이터베이스는 GitHub Actions를 통해 매일 업데이트됩니다. 최신 CVE 데이터를 얻으려면 주기적으로 `update-db`를 실행하세요.
### 기본 스캔```bash
# Scan a Docker image
dockerscan nginx:latest
# Scan with specific scanners
dockerscan --scanners cis,secrets ubuntu:22.04
# Scan and save reports
dockerscan alpine:latest --output /tmp/reports
# Quiet mode (suppress banner)
dockerscan -q nginx:latest
```
### 예제 출력```
╔══════════════════════════════════════════════════════════════════════════╗
║ ██████╗ ██████╗ ██████╗██╗ ██╗███████╗██████╗ ███████╗ ██████╗ █████╗ ███╗ ██╗
║ ██╔══██╗██╔═══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗██╔════╝██╔════╝██╔══██╗████╗ ██║
║ ██║ ██║██║ ██║██║ █████╔╝ █████╗ ██████╔╝███████╗██║ ███████║██╔██╗ ██║
║ ██║ ██║██║ ██║██║ ██╔═██╗ ██╔══╝ ██╔══██╗╚════██║██║ ██╔══██║██║╚██╗██║
║ ██████╔╝╚██████╔╝╚██████╗██║ ██╗███████╗██║ ██║███████║╚██████╗██║ ██║██║ ╚████║
║ ║
║ Advanced Docker Security Scanner v2.0.0 ║
║ ║
║ Author: Daniel Garcia (cr0hn) ║
║ Website: https://cr0hn.com ║
╚══════════════════════════════════════════════════════════════════════════════════════╝
🔍 Scanning image: nginx:latest
═══════════════════════════════════════════════════════════════════
SCAN RESULTS
═══════════════════════════════════════════════════════════════════
📊 Summary:
Total Findings: 47
Duration: 2.3s
🔴 By Severity:
Critical: 8
High: 15
Medium: 18
Low: 6
📁 By Category:
CIS-Benchmark: 12
Secrets: 8
Supply-Chain: 5
Vulnerability: 10
Runtime-Security: 12
📄 JSON report saved to: dockerscan-report.json
📄 SARIF report saved to: dockerscan-report.sarif
```
---
## 📖 사용법
### 명령줄 옵션```bash
dockerscan [COMMAND] [OPTIONS] <IMAGE>
Commands:
scan Scan a Docker image (default)
update-db Download or update the CVE database
Options: --from-file <path> Install from local SQLite file
version Show version information
help Show help message
Options:
-h, --help Show help message
-v, --version Show version
-q, --quiet Suppress banner output (quiet mode)
--scanners SCANNERS Comma-separated list of scanners to run
(default: all)
Options: cis,secrets,supplychain,vulnerabilities,runtime
--output DIR Output directory for reports (default: .)
--only-critical Show only critical/high severity findings
--verbose, -v Show scan progress (scanner names, findings count, image pull status). Output to stderr.
--debug Show verbose output plus internal errors and technical details. Output to stderr.
Authentication (for private registries):
--registry-user <username> Registry username
--registry-password <password> Registry password (not recommended, use env vars)
--registry <url> Registry URL (optional, auto-detected from image)
--docker-config <path> Path to Docker config file (default: ~/.docker/config.json)
Environment variables (recommended for CI/CD):
DOCKER_USERNAME or REGISTRY_USERNAME Registry username
DOCKER_PASSWORD or REGISTRY_PASSWORD Registry password or token
DOCKER_REGISTRY or REGISTRY Registry URL (optional)
Exit Codes:
0 No issues found
1 HIGH severity issues found
2 CRITICAL severity found
```
### 예제```bash
# Scan with all scanners (default)
dockerscan myapp:latest
# Only run specific scanners
dockerscan --scanners secrets,supplychain redis:7
# Save reports to specific directory
dockerscan --output /var/reports postgres:14
# Only show critical issues
dockerscan --only-critical production-app:v1.0
# Ver progreso del scan (scanner names, findings count, image pull status)
dockerscan --verbose ubuntu:22.04
# Debug detallado (errores internos, detalles técnicos)
dockerscan --debug ubuntu:22.04
# Scan private registry images (see Authentication section below)
dockerscan ghcr.io/myorg/private-app:v1.0
```
### 🔐 개인 레지스트리 인증
DockerScan은 개인 레지스트리 인증을 위한 세 가지 방법을 지원합니다:
#### 방법 1: Docker 구성 파일 (로컬 사용에 권장)
가장 편리한 방법 - 기존 Docker 자격 증명을 사용합니다:```bash
# First, authenticate with your registry using Docker
docker login ghcr.io
# Username: your-username
# Password: ghp_your-token-here
# Now DockerScan can use these credentials automatically
dockerscan ghcr.io/myorg/private-app:latest
```
DockerScan은 `~/.docker/config.json`에서 자격 증명을 자동으로 읽습니다. 이는 `docker login`으로 로그인한 모든 레지스트리에서 작동합니다.
**자격 증명 헬퍼가 완전히 지원됩니다.** DockerScan은 다음을 통해 자격 증명을 기본적으로 확인합니다:
- **`credsStore`** — 전역 자격 증명 헬퍼 (예: macOS Docker Desktop의 `osxkeychain`, Windows의 `wincred`, Linux의 `pass`)
- **`credHelpers`** — 레지스트리별 자격 증명 헬퍼 (`credsStore`보다 우선함)
- **자동 대체** — 지정된 헬퍼 바이너리가 설치되지 않은 경우 DockerScan은 `config.json`의 일반 텍스트 `auths` 블록으로 대체합니다.
**macOS에서 Docker Desktop**을 사용하는 경우 추가 구성 없이 즉시 작동합니다:```json
{
"credsStore": "osxkeychain"
}
```
#### 방법 2: 환경 변수 (CI/CD에 권장)
자동화 환경 및 CI/CD 파이프라인에 가장 적합합니다:```bash
# Set environment variables
export DOCKER_USERNAME=myusername
export DOCKER_PASSWORD=mytoken
# Scan private image
dockerscan ghcr.io/myorg/private-app:latest
# Or use alternative variable names
export REGISTRY_USERNAME=myusername
export REGISTRY_PASSWORD=mytoken
dockerscan myregistry.example.com/app:v1.0
```
**CI/CD 예시 (GitHub Actions):**```yaml
- name: Scan private image
env:
DOCKER_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
DOCKER_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
run: dockerscan ghcr.io/${{ github.repository }}:${{ github.sha }}
```
#### 방법 3: 명령줄 플래그 (권장되지 않음)
빠른 테스트 전용 (자격 증명이 프로세스 목록에 노출됨):```bash
dockerscan --registry-user myuser --registry-password mytoken ghcr.io/myorg/app:v1
```
**보안 경고:** 이 방법은 셸 기록과 프로세스 목록에 자격 증명을 노출합니다. 대신 환경 변수나 Docker 구성을 사용하세요.
### 레지스트리별 예제
#### Docker Hub (비공개 리포지토리)```bash
# Using Docker config
docker login docker.io
dockerscan myusername/private-repo:latest
# Using environment variables
export DOCKER_USERNAME=myusername
export DOCKER_PASSWORD=dckr_pat_XXXXXXXXXXXXX
dockerscan myusername/private-repo:latest
```
#### GitHub Container Registry (GHCR)```bash
# Using Docker config
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
dockerscan ghcr.io/myorg/myapp:v1.0
# Using environment variables
export DOCKER_USERNAME=myusername
export DOCKER_PASSWORD=ghp_XXXXXXXXXXXXXXXXXXXX
dockerscan ghcr.io/myorg/myapp:v1.0
```
#### AWS Elastic Container Registry (ECR)```bash
# Get login credentials from AWS
aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin \
123456789012.dkr.ecr.us-east-1.amazonaws.com
# Scan ECR image
dockerscan 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
# Or use environment variables with ECR credentials
export DOCKER_USERNAME=AWS
export DOCKER_PASSWORD=$(aws ecr get-login-password --region us-east-1)
dockerscan 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
```
#### Google Container Registry (GCR) / Artifact Registry```bash
# Authenticate with gcloud
gcloud auth configure-docker gcr.io
# Scan GCR image
dockerscan gcr.io/my-project/myapp:latest
# For Artifact Registry
gcloud auth configure-docker us-docker.pkg.dev
dockerscan us-docker.pkg.dev/my-project/my-repo/myapp:latest
# Or use service account JSON key
export DOCKER_USERNAME=_json_key
export DOCKER_PASSWORD="$(cat service-account-key.json)"
dockerscan gcr.io/my-project/myapp:latest
```
#### Azure Container Registry (ACR)```bash
# Login with Azure CLI
az acr login --name myregistry
# Scan ACR image
dockerscan myregistry.azurecr.io/myapp:v1.0
# Or use service principal credentials
export DOCKER_USERNAME=<service-principal-id>
export DOCKER_PASSWORD=<service-principal-password>
dockerscan myregistry.azurecr.io/myapp:v1.0
```
#### GitLab Container Registry```bash
# Using Docker config
docker login registry.gitlab.com
dockerscan registry.gitlab.com/mygroup/myproject/myapp:latest
# Using environment variables with deploy token
export DOCKER_USERNAME=gitlab+deploy-token-1
export DOCKER_PASSWORD=DEPLOY_TOKEN_HERE
dockerscan registry.gitlab.com/mygroup/myproject/myapp:latest
```
#### 자체 호스팅/비공개 레지스트리```bash
# Standard authentication
docker login myregistry.example.com:5000
dockerscan myregistry.example.com:5000/myapp:latest
# With environment variables
export DOCKER_USERNAME=admin
export DOCKER_PASSWORD=secret
dockerscan myregistry.example.com:5000/myapp:latest
# Insecure registries (not recommended for production)
# Add to Docker daemon config: /etc/docker/daemon.json
# {
# "insecure-registries": ["myregistry.example.com:5000"]
# }
```
### 인증 문제 해결
#### 일반적인 문제
**1. "authentication required" 오류**```bash
# Make sure you're logged in
docker login <registry>
# Or set environment variables
export DOCKER_USERNAME=your-username
export DOCKER_PASSWORD=your-token
```
**2. "unauthorized: authentication failed" 오류**
- 자격 증명이 올바른지 확인하세요
- 토큰이 만료되었는지 확인하세요 (특히 클라우드 제공업체의 경우)
- 계정에 이미지 풀 권한이 있는지 확인하세요
**3. AWS ECR "authorization token has expired"**```bash
# ECR tokens expire after 12 hours - refresh them
aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin \
123456789012.dkr.ecr.us-east-1.amazonaws.com
```
**4. Docker Hub의 속도 제한**
- 인증하여 속도 제한 증가 (무료 계정은 6시간에 200회 풀)
- 더 높은 제한을 위해 Docker Hub Pro 계정 사용 고려
**5. 자체 서명 인증서의 인증서 오류**
- 시스템 신뢰 저장소에 CA 인증서 추가
- 또는 Docker가 레지스트리를 신뢰하도록 구성 (Docker 문서 참조)
---
## 🔍 보안 스캐너
### CIS Docker 벤치마크
CIS Docker 벤치마크 v1.7.0에 대한 자동화된 규정 준수 검사:```bash
dockerscan --scanners cis nginx:latest
```
검사 항목은 다음과 같습니다:
- 컨테이너 사용자가 root가 아님
- 불필요한 패키지가 설치되지 않음
- HEALTHCHECK 명령어가 포함됨
- 특정 버전 태그 사용 (`:latest` 미사용)
- 최소한의 포트 노출
- 권한이 있는 컨테이너 없음
- Linux 역량 제한
- Seccomp/AppArmor 프로필 적용
- 읽기 전용 루트 파일시스템
- 70개 이상의 추가 검사...
### 공급망 보안
실제 공급망 공격 탐지:```bash
dockerscan --scanners supplychain suspicious-image:1.0
```
감지 대상:
- 이미지 없는 컨테이너 (문서 전용 공격)
- 암호화폐 채굴기 (xmrig, claymore 등)
- 백도어 라이브러리 (xz-utils 사례)
- 서명되지 않음/확인되지 않은 이미지
- 문서 내 피싱 시도
- 채굴 풀, C2 서버로의 연결
### 비밀 탐지
하드코딩된 비밀 찾기:```bash
dockerscan --scanners secrets webapp:prod
```
찾는 항목:
- 클라우드 자격 증명 (AWS, GCP, Azure)
- API 키 (40개 이상 서비스)
- 개인 키 및 인증서
- 데이터베이스 자격 증명
- Docker 레지스트리 인증
- 높은 엔트로피 문자열 (잠재적 알 수 없는 비밀)
### 취약점 스캐닝
알려진 CVE 탐지:```bash
dockerscan --scanners vulnerabilities node:16
```
다음 항목을 검사합니다:
- 중요 Docker CVE (2024-2025)
- 컨테이너 탈출 취약점
- BuildKit RCE 취약점
- 수명이 종료된 기본 이미지
- 취약한 패키지
### Runtime Security
런타임 구성을 감사합니다:```bash
dockerscan --scanners runtime running-container
```
Analyzes:
- Linux capabilities (CAP_SYS_ADMIN 등)
- Seccomp 프로필
- AppArmor/SELinux 정책
- 네임스페이스 격리
- Privileged 모드 사용
---
## 📁 출력 형식
### JSON 출력```json
{
"target": {
"image_name": "nginx:latest"
},
"start_time": "2024-11-22T10:30:00Z",
"findings": [
{
"id": "CIS-4.1",
"title": "Container should not run as root",
"severity": "HIGH",
"category": "CIS-Benchmark",
"description": "Running containers as root increases attack surface...",
"remediation": "Use USER instruction in Dockerfile..."
}
],
"summary": {
"total_findings": 47,
"by_severity": {
"CRITICAL": 8,
"HIGH": 15
}
}
}
```
### SARIF 출력
GitHub Security, Azure DevOps, VS Code와 호환 가능:```json
{
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "DockerScan",
"version": "2.0.0"
}
},
"results": [...]
}
]
}
```
---
## 💼 사용 사례
### 1. **CI/CD 파이프라인 통합**
**GitHub Actions:**```yaml
name: Docker Security Scan
on: [push]
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build Docker image
run: docker build -t myapp:${{ github.sha }} .
- name: Install DockerScan
run: |
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -o dockerscan
chmod +x dockerscan
- name: Update CVE Database
run: ./dockerscan update-db
- name: Run Security Scan
run: ./dockerscan -q myapp:${{ github.sha }}
- name: Upload SARIF results
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: dockerscan-report.sarif
```
**GitLab CI:**```yaml
docker-security-scan:
stage: test
script:
- docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
- wget https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -O dockerscan
- chmod +x dockerscan
- ./dockerscan update-db
- ./dockerscan -q $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
artifacts:
reports:
sast: dockerscan-report.sarif
```
### 2. **보안 감사**```bash
# Comprehensive audit of production images
for image in $(docker images --format "{{.Repository}}:{{.Tag}}"); do
echo "Scanning $image..."
dockerscan $image --output /audit-reports/
done
# Generate summary report
cat /audit-reports/*.json | jq -s '
{
total_images: length,
total_findings: map(.summary.total_findings) | add,
critical_findings: map(.summary.by_severity.CRITICAL // 0) | add
}
'
```
### 3. **배포 전 검증**```bash
# Fail deployment if critical issues found
dockerscan production-app:v2.0
exit_code=$?
if [ $exit_code -eq 2 ]; then
echo "❌ Critical vulnerabilities found. Deployment blocked."
exit 1
elif [ $exit_code -eq 1 ]; then
echo "⚠️ High severity issues found. Manual review required."
# Send notification...
else
echo "✅ No critical issues. Proceeding with deployment."
fi
```
### 4. **규정 준수 보고**```bash
# Generate CIS compliance report
dockerscan --scanners cis --only-critical all-production-images:* > cis-compliance-report.txt
# Weekly security scan for compliance
0 0 * * 0 /usr/local/bin/dockerscan --scanners cis,vulnerabilities production-images:latest --output /compliance/weekly/
```
### 5. **개발자 워크플로우**```bash
# Pre-commit hook
#!/bin/bash
# .git/hooks/pre-commit
docker build -t local-test:latest .
dockerscan --only-critical local-test:latest
if [ $? -ne 0 ]; then
echo "❌ Docker security scan failed. Fix issues before committing."
exit 1
fi
```
---
## 📊 다른 도구와 비교
| 기능 | DockerScan v2.0 | Trivy | Clair | Snyk | Grype |
|---------|----------------|-------|-------|------|-------|
| **CIS 벤치마크 v1.7** | ✅ 전체 (80+ 검사) | ❌ | ❌ | 부분 | ❌ |
| **공급망 탐지 (2024)** | ✅ 예 | ❌ | ❌ | ❌ | ❌ |
| **시크릿 스캐닝** | ✅ 40+ 패턴 | 기본 | ❌ | ✅ | ❌ |
| **CVE 데이터베이스** | ✅ 2024-2025 CVE | ✅ | ✅ | ✅ | ✅ |
| **런타임 보안** | ✅ 전체 | ❌ | ❌ | ❌ | ❌ |
| **SARIF 출력** | ✅ | ✅ | ❌ | ✅ | ✅ |
| **속도 (Go)** | ⚡ 매우 빠름 | ⚡ 매우 빠름 | 🐌 느림 | ⚡ 빠름 | ⚡ 매우 빠름 |
| **확장성** | ✅ 플러그인 시스템 | 제한적 | 제한적 | ❌ | 제한적 |
| **종료 코드** | ✅ CI/CD 준비 | ✅ | 부분 | ✅ | ✅ |
| **비용** | 🆓 무료 | 🆓 무료 | 🆓 무료 | 💰 유료 등급 | 🆓 무료 |
| **오프라인 모드** | ✅ | ✅ | ❌ | ❌ | ✅ |
| **라이선스** | 독점 소스 제공 | Apache-2.0 | Apache-2.0 | 독점 | Apache-2.0 |
### DockerScan을 선택해야 하는 이유
- **가장 포괄적**: CIS + 공급망 + 시크릿 + CVE + 런타임을 결합한 유일한 도구
- **최신 연구**: 2024-2025 실제 공격 기반
- **제로 구성**: 기본 설정으로 즉시 사용 가능
- **개발자 친화적**: 실행 가능한 수정 조치와 함께 아름다운 CLI 출력
- **엔터프라이즈 준비**: SARIF + 종료 코드 + JSON 출력
---
## 🏗️ 아키텍처
### 프로젝트 구조```
dockerscan/
├── logo.png # Project logo
├── cmd/
│ ├── dockerscan/ # Main CLI application
│ │ └── main.go
│ └── nvd2sqlite/ # CVE database builder tool
│ └── main.go
├── data/ # CVE database (auto-updated daily)
│ ├── latest.db.gz # Compressed SQLite database
│ └── metadata.json # Database version info
├── internal/
│ ├── scanner/ # Extensible scanner framework
│ │ ├── scanner.go # Scanner interface & registry
│ │ ├── cis/ # CIS Benchmark implementation
│ │ ├── secrets/ # Secrets detection
│ │ ├── supplychain/ # Supply chain attacks
│ │ ├── vulnerabilities/ # CVE scanning
│ │ └── runtime/ # Runtime security
│ ├── report/ # Report generators
│ │ ├── json.go # JSON reporter
│ │ └── sarif.go # SARIF reporter
---
[Read more](https://github.com/cr0hn/dockerscan)