설정 파일 점검 도구는 대개 정해진 규칙을 가지고 있어서, 우리 팀이 정한 약속을 넣기가 어렵습니다. conftest는 OPA의 언어인 Rego로 정책을 직접 쓰고 YAML이나 JSON 파일에 적용해 주는 도구입니다. 이 글은 docker-compose.yml을 대상으로 정책을 쓰고, 그 정책 자체를 단위 시험하고, 약한 파일과 고친 파일에 적용해 종료 코드를 확인합니다. 정책이 막으려는 위험이 실제로 있는지 docker.sock을 마운트한 컨테이너로 직접 확인한 것도 담았습니다. 테라폼은 checkov 글, 이미지는 Dockle 글에서 다뤘으므로 이 글은 compose 파일과 정책 작성 방법에 집중합니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11, Git Bash에서 실행) |
| conftest | v0.71.1 (openpolicyagent/conftest 이미지) |
| OPA | 1.21.1 (conftest에 포함) |
| 교차 확인용 | docker:cli, alpine |
conftest는 파일을 읽기만 하며 compose를 실행하지 않습니다. 컨테이너를 실제로 띄우는 것은 4번의 docker.sock 확인 한 곳뿐이고, 그때 쓴 컨테이너는 osk-fc-victim 하나입니다.
1. 정책 여덟 개
정책은 compose.rego 한 파일입니다. deny는 막는 규칙이고 warn은 경고만 하는 규칙입니다.
| 구분 | 규칙 | 걸리는 경우 |
|---|---|---|
| deny | privileged | privileged: true |
| deny | host 네트워크 | network_mode: host |
| deny | docker.sock | 볼륨 값에 docker.sock이 들어감 |
| deny | 이미지 태그 | 태그가 없거나 :latest(@sha256: 다이제스트는 허용) |
| deny | 평문 비밀값 | 이름에 password, secret, token, api_key가 든 환경 변수에 ${...}가 아닌 값 |
| warn | root 실행 | user 지정 없음 |
| warn | 읽기 전용 | read_only 없음 |
| warn | 포트 공개 | 127.0.0.1:로 시작하지 않는 포트 |
규칙을 막는 규칙과 경고하는 규칙으로 나눈 이유는 도입 단계에서 모든 위반을 한 번에 막으면 팀이 정책을 끄게 되기 때문입니다. 경고는 개선 목록으로 두고, 막는 규칙은 확실히 위험한 것만 골랐습니다.
2. 정책부터 시험하기
정책도 코드이므로 시험이 필요합니다. compose_test.rego에 규칙마다 걸려야 하는 입력과 걸리면 안 되는 입력을 한 쌍씩 넣었습니다(14개).
## 1. 정책 단위 시험(conftest verify)
14 tests, 14 passed, 0 warnings, 0 failures, 0 exceptions, 0 skipped
with input as {...}로 입력을 바꿔 넣는 방식이라 YAML 파일을 따로 만들지 않아도 됩니다. object.union(base, {"privileged": true})처럼 기본 입력에 한 가지만 덮어쓰면 시험이 짧아집니다.
3. 세 파일에 적용
| 파일 | 내용 |
|---|---|
compose.bad.yml |
nginx:latest에 privileged, host 네트워크, docker.sock 마운트, 태그 없는 postgres와 평문 비밀번호, 모든 인터페이스에 열린 포트 |
compose.warn.yml |
고친 파일에서 web의 user를 빼고 포트를 8080:80으로 되돌린 것 (막을 것은 없고 경고만 2개) |
compose.good.yml |
태그 고정, user와 read_only 지정, 포트는 127.0.0.1:, 비밀번호는 ${DB_PASSWORD}로 받음 |
[compose.bad.yml]
12 tests, 0 passed, 6 warnings, 6 failures, 0 exceptions
종료 코드: 기본 1, --fail-on-warn 2
[compose.warn.yml]
8 tests, 6 passed, 2 warnings, 0 failures, 0 exceptions
종료 코드: 기본 0, --fail-on-warn 1
[compose.good.yml]
8 tests, 8 passed, 0 warnings, 0 failures, 0 exceptions
종료 코드: 기본 0, --fail-on-warn 0

deny만 있으면 종료 코드 1, 경고만 있으면 기본은 0입니다. 경고를 막는 쪽으로 올리려면--fail-on-warn을 붙입니다. 경고만 있는 파일이 이 옵션에서 1이 되는 것을 확인했습니다.- 약한 파일에서
--fail-on-warn은 2를 돌려줬습니다. 실패(1)와 경고(2)를 구분하는 값으로 보이지만 문서까지 확인하지는 않았고, 이 버전에서 관찰한 값입니다. 파이프라인에서는 0이 아닌지만 판단하는 편이 안전합니다. - 고친 파일은 8개 시험을 모두 통과했습니다. 시험 개수가 12(약한 파일)와 8(고친 파일)로 다른 것은, 통과한 규칙은 규칙 하나로 세고 걸린 규칙은 메시지마다 세기 때문으로 추정합니다. 같은 정책이라도 파일에 따라 숫자가 달라집니다.
4. 막으려던 위험이 진짜인지 확인
정책은 "하지 말라"고만 말합니다. docker.sock 규칙이 왜 있는지 직접 확인했습니다. 먼저 osk-fc-victim이라는 시험용 컨테이너를 하나 띄우고, 다른 컨테이너 두 개에서 그 이름을 찾아봤습니다.
| 컨테이너 | docker ps --filter name=osk-fc-victim |
|---|---|
| 소켓 마운트 없음 | failed to connect to the docker API ... (호스트 도커에 닿지 못함) |
/var/run/docker.sock 마운트 |
osk-fc-victim (호스트의 컨테이너가 보임) |
소켓을 마운트한 컨테이너에서 docker stop osk-fc-victim을 실행하자 호스트에서 본 상태가 exited가 되었습니다. 이 PC의 Docker Desktop에서 확인한 결과이며, 컨테이너 안에서 호스트의 다른 컨테이너를 보고 멈출 수 있다는 점이 "호스트 전체 권한과 같다"는 정책 메시지의 근거입니다. 이 확인에서는 멈추는 것까지만 했고 호스트 파일 접근이나 새 컨테이너 만들기는 시도하지 않았습니다.
5. 정책을 일부러 깨 보기
정책 사본에서 contains(vol, "docker.sock")을 "docker.sockX"로 바꿔 규칙을 무력화한 뒤 단위 시험을 돌렸습니다. 원본은 건드리지 않았습니다.

14개 중 test_docker_sock_denied 하나가 실패해 종료 코드 1이 되었습니다. 규칙 이름이 아니라 문자열 한 글자를 바꾼 것이었는데도 시험이 바로 잡았습니다. 정책 시험이 없으면 이런 오타로 규칙이 조용히 꺼져도 새 compose 파일이 모두 통과합니다.
6. 파이프라인에 넣을 때
- 검사 단계:
conftest test compose.yml -p 정책폴더. 실패(deny)가 있으면 단계가 실패합니다. - 정책 저장소의 CI: 정책을 바꿀 때마다
conftest verify -p 정책폴더를 먼저 돌립니다. - 새 규칙은
warn으로 넣고 개선 목록을 본 뒤deny로 올립니다.
이 연결을 CI 설정으로 만들지는 않았습니다. 정책 번들 배포나 conftest push도 해 보지 않았습니다.
전체 코드
전체를 한 번에 돌리는 스크립트입니다. 아래 파일과 같은 폴더에서 실행합니다.
# conftest_demo.sh
#!/usr/bin/env bash
# docker-compose.yml 용 정책(Rego)을 시험하고, 약한 파일, 경고만 있는 파일, 고친 파일에 적용하고, 막으려던 위험이 진짜인지 확인한다.
# 준비: Docker, 같은 폴더에 compose.rego, compose_test.rego, compose.bad.yml, compose.warn.yml, compose.good.yml.
# 실행(Git Bash): bash conftest_demo.sh (약 1분)
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
CT() { docker run --rm -v "$HERE:/p:ro" -w /p openpolicyagent/conftest "$@"; }
cleanup() { docker rm -f osk-fc-victim >/dev/null 2>&1; }
cleanup
echo "## 1. 정책 단위 시험(conftest verify)"
CT verify -p . --no-color 2>&1 | tail -1
echo "## 2. 세 파일에 정책 적용"
for f in bad warn good; do
echo "[compose.$f.yml]"
CT test compose.$f.yml -p . --no-color 2>&1 | grep -E '^(FAIL|WARN)|tests,' | sed -E 's/ - compose\.[a-z]+\.yml - main - / /; s/^/ /'
CT test compose.$f.yml -p . --no-color >/dev/null 2>&1; a=$?
CT test compose.$f.yml -p . --no-color --fail-on-warn >/dev/null 2>&1; b=$?
echo " 종료 코드: 기본 $a, --fail-on-warn $b"
done
echo "## 3. 교차 확인: docker.sock 마운트가 왜 위험한가"
docker run -d --name osk-fc-victim --entrypoint sleep alpine 600 >/dev/null
echo -n " 소켓 마운트 없음: "; docker run --rm docker:cli docker ps --filter name=osk-fc-victim --format '{{.Names}}' 2>&1 | cut -c1-48
echo -n " 소켓 마운트 있음: "; docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker:cli docker ps --filter name=osk-fc-victim --format '{{.Names}}'
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker:cli docker stop osk-fc-victim >/dev/null
echo " 마운트한 컨테이너가 다른 컨테이너를 멈춘 뒤 상태: $(docker inspect -f '{{.State.Status}}' osk-fc-victim)"
cleanup
echo "## 끝"
정책을 일부러 깨서 단위 시험이 잡는지 보는 스크립트입니다.
# conftest_break.sh
#!/usr/bin/env bash
# 정책을 일부러 깨 보고, 단위 시험이 잡아내는지 확인한다. 원본 정책은 건드리지 않고 사본으로만 시험한다.
# 준비: Docker, 같은 폴더에 compose.rego, compose_test.rego.
# 실행(Git Bash): bash conftest_break.sh (약 10초)
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
OUT=../osk-fc-ct-out
rm -rf "$OUT"; mkdir -p "$OUT"; ABS="$(cd "$OUT" && pwd)"
cp compose.rego compose_test.rego "$OUT/"
echo "## 정책 사본에서 docker.sock 규칙의 글자를 일부러 틀리게 고침"
sed -i 's/contains(vol, "docker.sock")/contains(vol, "docker.sockX")/' "$OUT/compose.rego"
diff <(grep -n 'docker.sock' compose.rego | head -1) <(grep -n 'docker.sock' "$OUT/compose.rego" | head -1) | sed 's/^/ /'
echo "## 사본으로 단위 시험"
docker run --rm -v "$ABS:/p:ro" -w /p openpolicyagent/conftest verify -p . --no-color 2>&1 | grep -E 'FAIL|tests,' | sed 's/^/ /'
echo " 종료 코드 ${PIPESTATUS[0]}"
정책 파일입니다. deny 다섯 개와 warn 세 개가 들어 있습니다.
# compose.rego
package main
# docker-compose.yml 한 파일을 입력으로 받아 deny(막음)와 warn(경고)을 만든다.
unpinned(image) if not contains(image, ":")
unpinned(image) if endswith(image, ":latest")
pinned_by_digest(image) if contains(image, "@sha256:")
secret_name(key) if regex.match(`(?i)(password|passwd|secret|token|api_?key)`, key)
deny contains msg if {
some name, svc in input.services
svc.privileged == true
msg := sprintf("서비스 %s: privileged 를 쓰지 않습니다", [name])
}
deny contains msg if {
some name, svc in input.services
svc.network_mode == "host"
msg := sprintf("서비스 %s: network_mode host 를 쓰지 않습니다", [name])
}
deny contains msg if {
some name, svc in input.services
some vol in svc.volumes
is_string(vol)
contains(vol, "docker.sock")
msg := sprintf("서비스 %s: docker.sock 을 마운트하지 않습니다 (호스트 전체 권한과 같습니다)", [name])
}
deny contains msg if {
some name, svc in input.services
unpinned(svc.image)
not pinned_by_digest(svc.image)
msg := sprintf("서비스 %s: 이미지 %s 의 태그를 고정합니다 (latest 나 태그 없음 금지)", [name, svc.image])
}
deny contains msg if {
some name, svc in input.services
some key, value in svc.environment
secret_name(key)
is_string(value)
not startswith(value, "${")
msg := sprintf("서비스 %s: 환경 변수 %s 에 비밀값을 직접 적지 않습니다 (${변수}로 받습니다)", [name, key])
}
warn contains msg if {
some name, svc in input.services
not svc.user
msg := sprintf("서비스 %s: user 를 지정해 root 로 실행하지 않습니다", [name])
}
warn contains msg if {
some name, svc in input.services
not svc.read_only
msg := sprintf("서비스 %s: read_only: true 를 검토합니다", [name])
}
warn contains msg if {
some name, svc in input.services
some port in svc.ports
not startswith(sprintf("%v", [port]), "127.0.0.1:")
msg := sprintf("서비스 %s: 포트 %v 가 모든 인터페이스에 열립니다 (127.0.0.1: 로 제한을 검토합니다)", [name, port])
}
정책 단위 시험입니다.
# compose_test.rego
package main
# conftest verify 가 읽는 단위 시험이다. 규칙마다 걸려야 하는 입력과 걸리면 안 되는 입력을 한 쌍씩 둔다.
base := {"image": "app:1.0", "user": "1000", "read_only": true}
has(msgs, word) if {
some m in msgs
contains(m, word)
}
test_privileged_denied if {
has(deny, "privileged") with input as {"services": {"a": object.union(base, {"privileged": true})}}
}
test_privileged_absent_ok if {
not has(deny, "privileged") with input as {"services": {"a": base}}
}
test_host_network_denied if {
has(deny, "network_mode host") with input as {"services": {"a": object.union(base, {"network_mode": "host"})}}
}
test_docker_sock_denied if {
has(deny, "docker.sock") with input as {"services": {"a": object.union(base, {"volumes": ["/var/run/docker.sock:/var/run/docker.sock"]})}}
}
test_normal_volume_ok if {
not has(deny, "docker.sock") with input as {"services": {"a": object.union(base, {"volumes": ["data:/var/lib/data"]})}}
}
test_latest_tag_denied if {
has(deny, "태그를 고정") with input as {"services": {"a": object.union(base, {"image": "nginx:latest"})}}
}
test_no_tag_denied if {
has(deny, "태그를 고정") with input as {"services": {"a": object.union(base, {"image": "nginx"})}}
}
test_pinned_tag_ok if {
not has(deny, "태그를 고정") with input as {"services": {"a": base}}
}
test_digest_ok if {
not has(deny, "태그를 고정") with input as {"services": {"a": object.union(base, {"image": "nginx@sha256:abc"})}}
}
test_literal_password_denied if {
has(deny, "비밀값") with input as {"services": {"a": object.union(base, {"environment": {"DB_PASSWORD": "hunter2"}})}}
}
test_password_from_variable_ok if {
not has(deny, "비밀값") with input as {"services": {"a": object.union(base, {"environment": {"DB_PASSWORD": "${DB_PASSWORD}"}})}}
}
test_root_user_warned if {
has(warn, "user 를 지정") with input as {"services": {"a": {"image": "app:1.0"}}}
}
test_open_port_warned if {
has(warn, "모든 인터페이스") with input as {"services": {"a": object.union(base, {"ports": ["8080:80"]})}}
}
test_loopback_port_ok if {
not has(warn, "모든 인터페이스") with input as {"services": {"a": object.union(base, {"ports": ["127.0.0.1:8080:80"]})}}
}
일부러 약하게 쓴 compose 파일입니다. 실행하지 말고 검사만 합니다.
compose.bad.yml
services:
web:
image: nginx:latest
ports:
- "8080:80"
privileged: true
network_mode: host
volumes:
- /var/run/docker.sock:/var/run/docker.sock
db:
image: postgres
environment:
POSTGRES_PASSWORD: hunter2
POSTGRES_USER: app
ports:
- "5432:5432"
막을 것은 없고 경고만 있는 파일입니다.
compose.warn.yml
services:
web:
image: nginx:1.27-alpine
read_only: true
ports:
- "8080:80"
tmpfs:
- /var/cache/nginx
- /var/run
db:
image: postgres:16-alpine
user: "70:70"
read_only: true
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: app
ports:
- "127.0.0.1:5432:5432"
tmpfs:
- /tmp
- /var/run/postgresql
고친 파일입니다.
compose.good.yml
services:
web:
image: nginx:1.27-alpine
user: "101:101"
read_only: true
ports:
- "127.0.0.1:8080:80"
tmpfs:
- /var/cache/nginx
- /var/run
db:
image: postgres:16-alpine
user: "70:70"
read_only: true
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: app
ports:
- "127.0.0.1:5432:5432"
tmpfs:
- /tmp
- /var/run/postgresql
자주 막히는 곳
| 증상 | 원인 | 해결 |
|---|---|---|
Git Bash에서 docker run -v 경로 오류 |
경로 자동 변환 | export MSYS_NO_PATHCONV=1 |
한글 메시지를 cut -c로 자르면 깨짐 |
cut -c는 글자가 아니라 바이트 단위 |
자르지 않고 그대로 출력 |
소켓 없는 컨테이너의 오류가 tcp://docker:2375로 나옴 |
docker:cli는 호스트 소켓이 없으면 docker라는 이름의 서버로 접속을 시도 |
마운트 여부만 비교하면 되므로 메시지 앞부분만 확인 |
| 경고만 있는데 파이프라인이 통과함 | warn은 기본으로 실패시키지 않음 |
--fail-on-warn |
확인 범위
- 해 본 것: 2026-10-30, Windows 11 · Docker 29.5.3 · conftest 0.71.1(OPA 1.21.1)에서 정책 단위 시험 14개 통과, 약한 파일과 경고만 있는 파일과 고친 파일의 적용 결과와 종료 코드,
docker.sock을 마운트한 컨테이너가 다른 컨테이너를 보고 멈추는 것, 정책을 일부러 깬 사본의 시험 실패를 확인했습니다. 전체 스크립트를 두 번 실행해 결과가 같았고, 시험용 컨테이너를 지웠습니다. - 해 보지 않은 것: Kubernetes 매니페스트와 테라폼 plan용 정책, 환경 변수가 목록 형식인 compose 파일,
extends와 여러 파일 병합, 정책 번들 배포, CI 연동, 호스트 파일 접근 같은 소켓 악용 시도, Linux와 macOS. - 읽을 때 주의: 정책 여덟 개는 이 글의 샘플에 맞춘 예시입니다.
--fail-on-warn의 종료 코드 2는 이 버전에서 관찰한 값입니다. 소켓 확인은 내 PC의 시험용 컨테이너에서만 했습니다.
이 글의 다음 단계
- Dockle로 만들어진 컨테이너 이미지 점검하기: 비밀 노출, root 실행, 종료 코드 기준까지일부러 나쁘게 만든 이미지와 고친 이미지를 Dockle로 점검합니다. CIS-DI 지적을 하나씩 읽고, 베이스 이미지에서 나오는 오탐을 예외로 두고, 이미지 기록에서 ENV 비밀이 그대로 읽히는 것과 종료 코드 기준(--exit-level)을 실행해 확인합니다.
- Hadolint로 Dockerfile 점검하기: 열한 가지 지적을 읽고 고치고, CI 기준 정하기일부러 나쁘게 쓴 Dockerfile을 Hadolint에 넣어 지적 열한 건을 규칙 번호별로 읽고 고칩니다. 실패 기준(--failure-threshold), 예외 설정, 고친 파일의 빌드와 실행 사용자까지 실행해 확인합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com