Copy & Run

Hadolint로 Dockerfile 점검하기: 열한 가지 지적을 읽고 고치고, CI 기준 정하기

일부러 나쁘게 쓴 Dockerfile을 Hadolint에 넣어 지적 열한 건을 규칙 번호별로 읽고 고칩니다. 실패 기준(--failure-threshold), 예외 설정, 고친 파일의 빌드와 실행 사용자까지 실행해 확인합니다.

실습 노트 · 2026-10-29 발행 · 10분 · 2026-10 확인

이미지를 스캔하기 전에 이미지를 만드는 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 하나로 다시 실행할 수 있습니다.

이 단계의 파일 내려받기: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한 것도 일부러 넣었습니다. 아래에서 보듯 이 줄은 지적되지 않았습니다.
이 단계의 파일 내려받기:Dockerfile.badapp.py

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절에서 직접 고칩니다.

lint_demo.sh 실행 결과 앞부분에서 나쁜 Dockerfile 여덟 줄과 줄 번호별 지적 열한 건이 규칙 번호와 수준(warning, info, error)과 함께 나오고, 수준별 집계가 warning 7, info 3, error 1인 것을 확인합니다.
lint_demo.sh 실행 결과 앞부분에서 나쁜 Dockerfile 여덟 줄과 줄 번호별 지적 열한 건이 규칙 번호와 수준(warning, info, error)과 함께 나오고, 수준별 집계가 warning 7, info 3, error 1인 것을 확인합니다.

이 단계의 파일 내려받기:Dockerfile.badlint_demo.sh

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이었습니다.

이 단계의 파일 내려받기:Dockerfile.goodapp.py

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까지 막으면 기존 파일이 모두 실패해서 도구가 외면받기 쉽습니다.

이 단계의 파일 내려받기:Dockerfile.warnonlyapp.py

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가 실제로는 존재하지 않는 스크립트를 내려받아 실행하는 줄이어서, 빌드해도 의미 있는 결과가 나오지 않기 때문입니다. 이 한 줄이 위험한 이유도 내려받은 내용을 검증 없이 실행한다는 데 있습니다.

lint_demo.sh 실행 결과 뒷부분에서 종료 코드 표(warnonly는 error 기준 0, 나머지는 1), 예외 설정 뒤 지적이 9건으로 줄어든 것, 고친 이미지가 빌드되어 사용자 10001로 실행되고 헬스체크가 있는 것을 확인합니다.
lint_demo.sh 실행 결과 뒷부분에서 종료 코드 표(warnonly는 error 기준 0, 나머지는 1), 예외 설정 뒤 지적이 9건으로 줄어든 것, 고친 이미지가 빌드되어 사용자 10001로 실행되고 헬스체크가 있는 것을 확인합니다.

이 단계의 파일 내려받기:Dockerfile.goodapp.pylint_demo.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

같은 카테고리의 글