---

DockSec이란?

DockSec은 복잡한 보안 스캔 결과와 개발자가 실제로 적용할 수 있는 수정 사항 사이의 간극을 메우는 OWASP Lab 프로젝트입니다. 업계 표준 스캐너(Trivy, Hadolint, Docker Scout)를 AI와 통합하여 상황을 인식한 보안 분석을 제공합니다.

200개 이상의 CVE 목록으로 압도하는 대신, DockSec은 다음과 같이 동작합니다:

• 특정 컨테이너 구성에 실제로 영향을 미치는 항목을 우선순위로 정렬합니다.
• 보안 전문 용어가 아닌 쉬운 말로 취약점을 설명합니다.
• Dockerfile에 대한 구체적인 수정 사항을 제안합니다.
• 팀을 위한 전문적이고 인터랙티브한 보안 보고서를 생성합니다.

모든 스캔은 로컬에서 수행되며, 사용자의 머신을 벗어나는 것은 사용자가 선택한 AI 제공자에게 전송되는 (비밀이 마스킹된) 파일 내용뿐입니다. 로컬 모델이나 스캔 전용 모드를 사용하면 아무것도 외부로 나가지 않습니다. 데이터 흐름과 프라이버시를 참고하세요.

---

동작 방식

DockSec은 다섯 단계의 파이프라인을 따릅니다:

1. 스캔: 사용자 환경에서 Trivy(이미지 취약점 및 Dockerfile 잘못된 구성), Hadolint, Docker Scout를 로컬로 실행합니다.
2. 우선순위 지정: 모든 CVE 발견 항목을 심각도와 EPSS 악용 가능성을 결합하여 순위를 매기므로, 발견된 순서가 아니라 먼저 수정해야 할 항목 순서로 목록이 정렬됩니다.
3. 상관 분석: 개별 발견 항목들이 결합하여 하나의 공격 경로를 이루는 익스플로잇 체인을 탐지합니다. 인터넷에 노출된 서비스가 접근할 수 있는 자격 증명이 있는 데이터베이스는 서로 무관한 두 개의 발견 항목이 아니라 하나의 체인입니다. API 키가 있으면 AI가 전체 스캔 출력을 추론하여 이를 순위 매기고, 설명하고, 확장합니다.
4. 권장 사항 제시: 복사해서 실행할 수 있는 수정 명령과 구체적인 Dockerfile 또는 compose 변경 사항을 생성하고, 그것이 해결하는 발견 항목 수를 명시합니다.
5. 보고서 작성: 실행 가능한 결과를 HTML, PDF, JSON, CSV, Markdown, SARIF, CycloneDX SBOM으로 내보냅니다.

---

시작하기

1. 사전 요구 사항

DockSec은 로컬 스캐너를 오케스트레이션하므로 다음이 필요합니다:

요구 사항	필요한 용도	설치
Python 3.12+	DockSec 자체	python.org
Trivy	모든 스캔(필수)	brew install trivy 또는 Trivy 문서
Hadolint	Dockerfile 린팅	brew install hadolint 또는 Hadolint 문서
Docker	이미지 스캔(-i)	Docker 문서

또는 DockSec이 Trivy와 Hadolint를 대신 설치하도록 할 수 있습니다:```bash python -m docksec.setup_external_tools

### 2. DockSec 설치```bash
# Full install with AI analysis support (recommended)
pip install "docksec[ai]"

# Or the slim, scan-only core (no LLM dependencies, no API key needed)
pip install docksec

3. 첫 스캔 실행하기

로컬 스캔에는 API 키가 필요하지 않습니다:```bash docksec Dockerfile --scan-only

모든 스캔은 결과 요약으로 끝납니다: 심각도 테이블, 등급이 포함된 0-100 보안 점수,
"Quick take" 액션 블록, 생성된 보고서(기본적으로
`~/.docksec/results/`에 저장됨), 그리고 제안된 다음 명령입니다.

### 4. AI 분석 활성화

AI 분석은 발견 사항을 설명하고 수정 방법을 제안합니다. 제공자를 선택하고, API 키를 설정한 후 실행하세요:```bash
# OpenAI (default provider)
export OPENAI_API_KEY="sk-..."
docksec Dockerfile

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
docksec Dockerfile --ai-only --provider anthropic --model claude-sonnet-5

# Google Gemini
export GOOGLE_API_KEY="..."
docksec Dockerfile --ai-only --provider google

# Ollama (fully local, no API key, data never leaves your machine)
docksec Dockerfile --ai-only --provider ollama --model llama3.1

각 제공자는 합리적인 기본 모델을 가지고 있으므로(OpenAI: gpt-4o, Anthropic: claude-haiku-4-5, Google: gemini-1.5-pro, Ollama: llama3.1), --model은 선택 사항입니다. 플래그를 반복하지 않으려면 환경 변수를 설정하거나(또는 실행하는 디렉터리의 .env 파일에 넣으세요 - DockSec가 자동으로 로드합니다):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile

AI 제공업체로 콘텐츠가 전송되기 전에 비밀번호, 토큰, API 키, 개인 키 블록처럼 보이는 값은 자동으로 마스킹됩니다. [데이터 흐름 및 개인정보 보호](#data-flow-and-privacy)를 참조하세요.

### 5. 또는 컨테이너 이미지 실행 (설치할 필요 없음)

게시된 이미지에는 Trivy와 Hadolint의 고정된 버전이 포함되어 있으므로 설치할 것도, 구성할 것도 없습니다:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_DOCKERFILE=Dockerfile \
  -e INPUT_SCAN_ONLY=true \
  ghcr.io/owasp/docksec:latest

매 릴리스마다 멀티 아키텍처(amd64 및 arm64)로 게시됩니다. CI에서는 latest 대신 특정 버전(ghcr.io/owasp/docksec:2026.9.21)이나 마이너 시리즈(ghcr.io/owasp/docksec:2026.9)에 고정하세요. 모든 이미지에는 빌드 출처 증명이 포함되어 있습니다:```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec

이 이미지는 GitHub Action과 동일한 `INPUT_*` 변수를 읽으므로, 모든 Action 입력이 여기서도 작동합니다: `INPUT_IMAGE`, `INPUT_COMPOSE`, `INPUT_SEVERITY`, `INPUT_FAIL_ON`, `INPUT_FORMAT`, `INPUT_SARIF`, `INPUT_OUTPUT_DIR`. 컨테이너가 종료된 후에도 보고서를 유지하려면 마운트된 위치 어딘가에 보고서를 작성하세요:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_COMPOSE=docker-compose.yml \
  -e INPUT_SCAN_ONLY=true \
  -e INPUT_FORMAT=json,html \
  -e INPUT_OUTPUT_DIR=/github/workspace/docksec-reports \
  ghcr.io/owasp/docksec:latest

6. 또는 GitHub Action 사용```yaml

• name: Run DockSec AI Scanner uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' openai_api_key: ${{ secrets.OPENAI_API_KEY }}

## 일반 명령어```bash
# Scan Dockerfile + Docker image (AI + scanners)
docksec Dockerfile -i myapp:latest

# Scan a Docker Compose file and all its services
docksec --compose docker-compose.yml

# Scan only a Docker image
docksec --image-only -i myapp:latest

# Fast local scan, no AI, no API key
docksec Dockerfile --scan-only

# Choose which severity levels the image scan reports (default: CRITICAL,HIGH)
docksec -i myapp:latest --image-only --severity CRITICAL,HIGH,MEDIUM