이미지를 스캔하기 전에 이미지를 만드는 Dockerfile부터 점검하면 문제를 더 적은 비용으로 잡을 수 있습니다. Hadolint는 Dockerfile을 읽어 권장하지 않는 작성 방식을 규칙 번호와 함께 알려 주는 오픈소스 도구입니다. 이미지를 만들지 않고 파일만 읽으므로 몇 초면 끝나서 커밋 전 검사나 CI 첫 단계에 넣기 좋습니다. 이 글에서는 일부러 나쁘게 쓴 Dockerfile을 넣어 지적을 하나씩 읽고, 고친 파일이 통과하는지와 실제로 빌드되어 안전한 사용자로 도는지까지 확인합니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11) |
| Hadolint | 2.15.1 (hadolint/hadolint 이미지, 설치 없이 컨테이너로 실행) |
| 파이썬 | 3.12 (JSON 결과 집계용) |
Hadolint는 docker run --rm -i hadolint/hadolint < Dockerfile처럼 파일을 표준 입력으로 넘기는 방식이 가장 단순합니다. 이 글의 모든 명령은 아래 "전체 코드"의 lint_demo.sh 하나로 다시 실행할 수 있습니다.
1. 나쁜 Dockerfile
초보자가 흔히 쓰는 모양을 여덟 줄로 모았습니다. 이 파일은 Dockerfile.bad입니다.
FROM python
RUN apt-get update
RUN apt-get install -y curl git
RUN curl -sL https://example.com/install.sh | sh
ADD app.py /app/
RUN cd /app && pip install flask
EXPOSE 22
CMD python /app/app.py
- 태그 없는
FROM python, 한 줄씩 나뉜RUN, 설치 스크립트를 내려받아 바로 실행(curl | sh),ADD,cd뒤pip install, 쉘 형식CMD가 한 파일에 들어 있습니다. - 22번 포트를
EXPOSE한 것도 일부러 넣었습니다. 아래에서 보듯 이 줄은 지적되지 않았습니다.
2. 점검 결과 읽기
docker run --rm -i hadolint/hadolint hadolint --no-color - < Dockerfile.bad
지적은 11건이었고 수준별로 error 1, warning 7, info 3이었습니다. 규칙 번호별로 읽으면 다음과 같습니다.
| 줄 | 규칙 | 수준 | 뜻과 고치는 방법 |
|---|---|---|---|
| 1 | DL3006 | warning | 이미지 태그가 없으면 latest가 되어 빌드할 때마다 내용이 달라집니다. python:3.12-alpine처럼 태그를 고정합니다 |
| 2 | DL3009 | info | apt-get update가 남긴 패키지 목록(/var/lib/apt/lists)이 이미지에 남습니다. 같은 RUN에서 지웁니다 |
| 3 | DL3059 | info | RUN이 연달아 있습니다. 한 줄로 합치면 레이어가 줄어듭니다 |
| 3 | DL3008 | warning | apt-get install의 패키지 버전을 고정하지 않았습니다 |
| 3 | DL3015 | info | 추천 패키지까지 설치합니다. --no-install-recommends를 붙입니다 |
| 4 | DL4006 | warning | 파이프(`curl ... |
| 5 | DL3020 | error | 폴더와 파일을 넣을 때는 ADD가 아니라 COPY를 씁니다. ADD는 URL과 압축 풀기까지 하므로 의도하지 않은 동작이 생깁니다 |
| 6 | DL3042 | warning | pip install이 캐시를 이미지에 남깁니다. --no-cache-dir을 붙입니다 |
| 6 | DL3013 | warning | pip install의 패키지 버전을 고정하지 않았습니다 |
| 6 | DL3003 | warning | cd로 이동하지 말고 WORKDIR를 씁니다 |
| 8 | DL3025 | warning | CMD python ...은 쉘을 거쳐 실행됩니다. CMD ["python", "..."]처럼 배열로 씁니다 |
세 가지를 눈여겨봅니다.
- error는 하나뿐입니다.
ADD를 쓴 줄(DL3020)만 error이고 나머지는 warning과 info입니다. 수준은 규칙마다 정해져 있습니다. - 같은 줄에 규칙이 여러 개 걸립니다. 3번 줄 하나에 DL3059, DL3008, DL3015가 모두 붙었습니다.
- 지적되지 않은 것도 있습니다.
EXPOSE 22(SSH 포트 노출)와 컨테이너가 root로 도는 것은 이 파일에서 지적되지 않았습니다. Hadolint는 작성 방식을 보는 도구이지 보안 점검 전체를 대신하지 않습니다. 사용자 지정은 아래 3절에서 직접 고칩니다.

3. 고친 Dockerfile
지적을 모두 반영한 Dockerfile.good입니다.
FROM python:3.12-alpine
RUN apk add --no-cache curl=~8 \
&& adduser -D -u 10001 appuser
WORKDIR /app
COPY app.py /app/
USER 10001
HEALTHCHECK --interval=30s --timeout=3s CMD ["python", "-c", "print('ok')"]
CMD ["python", "/app/app.py"]
바꾼 내용은 다음과 같습니다.
- 태그를 고정했고(DL3006),
apk add --no-cache로 패키지 목록 캐시를 남기지 않습니다.curl=~8은 8 계열 버전으로 고정한다는 뜻입니다. - 설치와 사용자 만들기를 한
RUN으로 합쳤고(DL3059),WORKDIR를 썼고(DL3003),ADD대신COPY를 썼습니다(DL3020). USER 10001로 root가 아닌 사용자로 실행합니다. 숫자로 적은 것은 처음에USER appuser로 썼더니 Hadolint가 DL3066(이름으로 지정한 사용자는 호스트에서 해석되지 않을 수 있음)으로 알려 주었기 때문입니다.HEALTHCHECK도 배열 형식으로 썼습니다. 처음에HEALTHCHECK ... CMD python -c ...처럼 쉘 형식으로 쓰자 DL3025가 한 번 더 나왔습니다.
고친 파일을 같은 명령에 넣자 지적이 없었고 종료 코드는 0이었습니다.
4. 종료 코드와 실패 기준
CI에서 Hadolint를 쓸 때 중요한 것은 어떤 수준부터 빌드를 막을지입니다. 기본 설정에서는 info까지 모두 실패로 봅니다. 이 기준은 --failure-threshold로 바꿉니다. 이 값 이상의 지적이 하나라도 있으면 종료 코드 1이 나옵니다.
비교용으로 warning 한 건과 info 한 건만 있는 Dockerfile.warnonly를 만들었습니다.
FROM python:3.12-alpine
RUN echo one
RUN echo two
WORKDIR /app
COPY app.py /app/
CMD python /app/app.py
| 파일 | --failure-threshold |
종료 코드 | 이유 |
|---|---|---|---|
| warnonly | error | 0 | error가 없으므로 통과 |
| warnonly | warning | 1 | warning(DL3025)이 있음 |
| warnonly | info | 1 | warning과 info가 있음 |
| bad | error | 1 | error(DL3020)가 있음 |
| bad | warning | 1 | warning과 error가 있음 |
| bad | info | 1 | info, warning, error가 모두 있음 |
처음 도입하는 프로젝트라면 --failure-threshold error로 시작해 막힌 것만 고치고, 정리가 되면 warning으로 올리는 순서가 현실적입니다. 처음부터 info까지 막으면 기존 파일이 모두 실패해서 도구가 외면받기 쉽습니다.
5. 예외 설정
팀에서 적용하지 않기로 한 규칙은 .hadolint.yaml에 적어 제외합니다. 여기서는 DL3059(RUN 합치기)와 DL3009(apt 목록 삭제)를 제외했습니다.
ignored:
- DL3059
- DL3009
제외하자 지적이 11건에서 9건이 되었습니다(info 3건 중 2건이 빠지고 warning 7, info 1, error 1이 남음). 규칙을 제외할 때는 이유를 같은 파일에 주석으로 남기고, 한 줄에만 예외가 필요하면 Dockerfile 안에 # hadolint ignore=DL3059 주석을 쓰는 방법도 있습니다. 이 글에서는 인라인 주석 방식은 시험하지 않았습니다.
6. 고친 파일을 실제로 빌드하고 실행하기
린트를 통과해도 빌드가 되는지는 별개입니다. 고친 파일을 빌드하고 확인한 결과입니다.
| 확인 | 결과 |
|---|---|
| 빌드 | 성공 |
실행 사용자(id -u) |
10001 (root가 아님) |
| 앱 출력 | hello from container |
| 이미지 크기 | 20,577,033바이트(약 20MB) |
| 이미지 설정에 기록된 사용자 | 10001 |
| 헬스체크 | 있음 |
나쁜 파일은 빌드해 보지 않았습니다. curl -sL https://example.com/install.sh | sh가 실제로는 존재하지 않는 스크립트를 내려받아 실행하는 줄이어서, 빌드해도 의미 있는 결과가 나오지 않기 때문입니다. 이 한 줄이 위험한 이유도 내려받은 내용을 검증 없이 실행한다는 데 있습니다.

7. CI에 넣는 방법
표준 입력 방식은 CI에서도 그대로 씁니다.
docker run --rm -i hadolint/hadolint hadolint --failure-threshold warning - < Dockerfile
저장소에 Dockerfile이 여럿이면 find . -name 'Dockerfile*'로 찾아 반복합니다. 결과를 코드 호스팅 서비스의 보안 화면에 올리려면 -f sarif로 출력하는 방법이 있지만, 이 글에서는 시험하지 않았습니다. 앞의 Trivy 이미지 스캔 글과 합치면 Dockerfile 작성 단계(Hadolint)와 만들어진 이미지 단계(Trivy)에서 모두 검사할 수 있습니다.
전체 코드
아래 파일들을 같은 폴더에 두고 app.py(한 줄짜리 출력 프로그램)도 만든 뒤 bash lint_demo.sh로 실행합니다. 이 PC에서는 약 1분이 걸렸습니다. 끝에서 시험 이미지(osk-hadolint-good)만 지웁니다. 예외 설정 파일은 스크립트가 만들고 지웁니다.
app.py
print("hello from container")
Dockerfile.bad
FROM python
RUN apt-get update
RUN apt-get install -y curl git
RUN curl -sL https://example.com/install.sh | sh
ADD app.py /app/
RUN cd /app && pip install flask
EXPOSE 22
CMD python /app/app.py
Dockerfile.good
FROM python:3.12-alpine
RUN apk add --no-cache curl=~8 \
&& adduser -D -u 10001 appuser
WORKDIR /app
COPY app.py /app/
USER 10001
HEALTHCHECK --interval=30s --timeout=3s CMD ["python", "-c", "print('ok')"]
CMD ["python", "/app/app.py"]
Dockerfile.warnonly
FROM python:3.12-alpine
RUN echo one
RUN echo two
WORKDIR /app
COPY app.py /app/
CMD python /app/app.py
lint_demo.sh
#!/usr/bin/env bash
# Hadolint 로 Dockerfile 을 점검한다: 나쁜 파일의 지적, 고친 파일, 실패 기준, 예외 설정, 고친 파일 빌드.
# 준비: Docker, 파이썬(집계용). Hadolint 는 컨테이너로 실행한다.
# 실행(Git Bash): bash lint_demo.sh (약 1분)
set -u
export MSYS_NO_PATHCONV=1
H="docker run --rm -i hadolint/hadolint hadolint"
count() { python -X utf8 -c "
import json, sys
from collections import Counter
d = json.load(sys.stdin)
c = Counter(x['level'] for x in d)
print('지적', len(d), '건', dict(c))
"; }
echo "## 1. 나쁜 Dockerfile 점검(Dockerfile.bad, 아홉 줄)"
cat Dockerfile.bad
echo "---"
$H --no-color - < Dockerfile.bad | sed 's/^-:/줄 /'
echo "## 2. 수준별 집계(JSON 출력)"
$H -f json - < Dockerfile.bad 2>/dev/null | count
echo "## 3. 고친 Dockerfile 점검(Dockerfile.good)"
$H --no-color - < Dockerfile.good; echo "종료 코드: $?"
echo "## 4. 종료 코드: 어느 수준부터 실패로 볼까(--failure-threshold)"
echo "(Dockerfile.warnonly 는 warning 한 건과 info 한 건만 있는 파일, Dockerfile.bad 는 error 가 있는 파일)"
$H --no-color - < Dockerfile.warnonly | sed 's/^-:/줄 /'
for f in Dockerfile.warnonly Dockerfile.bad; do
for t in error warning info; do
$H --failure-threshold $t - < $f >/dev/null 2>&1; echo "$f threshold=$t 종료 코드: $?"
done
done
echo "## 5. 예외 설정(.hadolint.yaml): DL3059(RUN 합치기), DL3009(apt 목록 삭제) 제외"
printf 'ignored:\n - DL3059\n - DL3009\n' > .hadolint.yaml
docker run --rm -i -v "$(pwd -W 2>/dev/null || pwd)/.hadolint.yaml:/.config/hadolint.yaml:ro" hadolint/hadolint hadolint -f json - < Dockerfile.bad 2>/dev/null | count
rm -f .hadolint.yaml
echo "## 6. 고친 Dockerfile 을 실제로 빌드하고 실행"
docker build -q -f Dockerfile.good -t osk-hadolint-good . >/dev/null && echo "빌드 성공"
echo "실행 사용자: $(docker run --rm osk-hadolint-good id -u)"
echo "앱 출력: $(docker run --rm osk-hadolint-good)"
docker image inspect osk-hadolint-good --format '크기 {{.Size}} 바이트, 사용자 {{.Config.User}}, 헬스체크 {{if .Config.Healthcheck}}있음{{else}}없음{{end}}'
docker rmi -f osk-hadolint-good >/dev/null && echo "시험 이미지 삭제"
자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
| 한글 윈도우에서 색 코드가 깨져 보입니다 | --no-color를 붙입니다. 이 글의 출력은 모두 색을 껐습니다 |
Git Bash에서 -v 경로가 이상하게 바뀝니다 |
export MSYS_NO_PATHCONV=1을 하고, 경로는 pwd -W로 윈도우 형식으로 줍니다 |
| 파이프로 넘겼더니 종료 코드가 0입니다 | 파이프 뒤 명령의 코드가 보입니다. ${PIPESTATUS[0]}로 Hadolint의 코드를 읽습니다 |
줄 번호가 -:3처럼 나옵니다 |
파일 이름 대신 표준 입력(-)을 쓴 표시입니다. 파일 경로를 주면 이름이 나옵니다 |
| 규칙 번호의 뜻을 모르겠습니다 | 프로젝트 문서의 규칙 목록에서 번호로 찾습니다. 이 글은 문서를 열어 보지 않고 출력 문구만 옮겼습니다 |
확인 범위
- 해 본 것: 2026-10-29, Windows 11 · Docker 29.5.3 · Hadolint 2.15.1에서 나쁜 파일 점검(11건), 고친 파일 점검(0건),
--failure-threshold세 값, 예외 설정 파일, 고친 파일의 빌드와 실행(사용자 10001)을 실행했습니다. 끝난 뒤 시험 이미지를 지웠습니다. - 해 보지 않은 것: 인라인
# hadolint ignore주석, SARIF 출력, 여러 단계 빌드(multi-stage)의 점검, 나쁜 파일의 빌드, Linux와 macOS, 에디터 연동. - 읽을 때 주의: 규칙의 수준(error, warning, info)은 이 버전의 값이며 버전에 따라 달라질 수 있습니다. 린트를 통과했다고 이미지가 안전하다는 뜻은 아닙니다. 베이스 이미지와 패키지의 취약점은 이미지 스캔으로 따로 봅니다.
이 글의 다음 단계
- conftest와 Rego로 docker-compose 정책 만들기Rego로 docker-compose.yml 정책 여덟 개(privileged, host 네트워크, docker.sock 마운트, 이미지 태그, 평문 비밀번호, root 실행 등)를 직접 쓰고 conftest verify로 시험합니다. 약한 파일, 경고만 있는 파일, 고친 파일의 종료 코드를 비교하고 docker.sock이 왜 위험한지 컨테이너로 확인하며 정책을 일부러 깨서 시험이 잡는지도 봅니다.
- Dockle로 만들어진 컨테이너 이미지 점검하기: 비밀 노출, root 실행, 종료 코드 기준까지일부러 나쁘게 만든 이미지와 고친 이미지를 Dockle로 점검합니다. CIS-DI 지적을 하나씩 읽고, 베이스 이미지에서 나오는 오탐을 예외로 두고, 이미지 기록에서 ENV 비밀이 그대로 읽히는 것과 종료 코드 기준(--exit-level)을 실행해 확인합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com