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

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

- 주소: https://copyandrun.com/blog/hadolint-dockerfile-lint/
- 분야: DevSecOps
- 발행일: 2026-10-29
- 태그: Hadolint, Dockerfile, 린트, 컨테이너 보안

이미지를 스캔하기 전에 이미지를 만드는 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`입니다.

```dockerfile
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. 점검 결과 읽기

```bash
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 ... | sh`)가 있는데 `pipefail`이 없어, 앞 명령이 실패해도 뒤가 성공하면 빌드가 통과합니다 |
| 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인 것을 확인합니다.](https://copyandrun.com/img/hadolint-dockerfile-lint/01-나쁜-Dockerfile-점검.png)

## 3. 고친 Dockerfile

지적을 모두 반영한 `Dockerfile.good`입니다.

```dockerfile
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`를 만들었습니다.

```dockerfile
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 목록 삭제)를 제외했습니다.

```yaml
ignored:
  - DL3059
  - DL3009
```

제외하자 지적이 11건에서 9건이 되었습니다(info 3건 중 2건이 빠지고 warning 7, info 1, error 1이 남음). 규칙을 제외할 때는 이유를 같은 파일에 주석으로 남기고, 한 줄에만 예외가 필요하면 Dockerfile 안에 `# hadolint ignore=DL3059` 주석을 쓰는 방법도 있습니다. 이 글에서는 인라인 주석 방식은 시험하지 않았습니다.

## 6. 고친 파일을 실제로 빌드하고 실행하기

<!-- files: Dockerfile.good, app.py -->

린트를 통과해도 빌드가 되는지는 별개입니다. 고친 파일을 빌드하고 확인한 결과입니다.

| 확인 | 결과 |
|---|---|
| 빌드 | 성공 |
| 실행 사용자(`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로 실행되고 헬스체크가 있는 것을 확인합니다.](https://copyandrun.com/img/hadolint-dockerfile-lint/02-기준-예외-빌드.png)

## 7. CI에 넣는 방법

표준 입력 방식은 CI에서도 그대로 씁니다.

```bash
docker run --rm -i hadolint/hadolint hadolint --failure-threshold warning - < Dockerfile
```

저장소에 Dockerfile이 여럿이면 `find . -name 'Dockerfile*'`로 찾아 반복합니다. 결과를 코드 호스팅 서비스의 보안 화면에 올리려면 `-f sarif`로 출력하는 방법이 있지만, 이 글에서는 시험하지 않았습니다. 앞의 [Trivy 이미지 스캔 글](/blog/trivy-image-scan-gate/)과 합치면 Dockerfile 작성 단계(Hadolint)와 만들어진 이미지 단계(Trivy)에서 모두 검사할 수 있습니다.

## 전체 코드

아래 파일들을 같은 폴더에 두고 `app.py`(한 줄짜리 출력 프로그램)도 만든 뒤 `bash lint_demo.sh`로 실행합니다. 이 PC에서는 약 1분이 걸렸습니다. 끝에서 시험 이미지(`osk-hadolint-good`)만 지웁니다. 예외 설정 파일은 스크립트가 만들고 지웁니다.

`app.py`

```python
print("hello from container")
```

`Dockerfile.bad`

```dockerfile
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`

```dockerfile
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`

```dockerfile
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`

```bash
#!/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)은 이 버전의 값이며 버전에 따라 달라질 수 있습니다. 린트를 통과했다고 이미지가 안전하다는 뜻은 아닙니다. 베이스 이미지와 패키지의 취약점은 이미지 스캔으로 따로 봅니다.
