VPN 터널은 설정이 틀려도 오류 문구가 거의 나오지 않습니다. 맞는 키로 맞는 주소를 허용했을 때만 통신이 되고, 틀리면 조용히 패킷이 사라집니다. 그래서 "연결됐다"를 무엇으로 판단할지가 중요합니다. 이 글에서는 컨테이너 두 개에 WireGuard를 올려 정상 설정과 틀린 설정 두 가지를 만들고, 핸드셰이크 시각과 ping 결과로 같은 점검을 적용합니다. 이어서 터널로 보낸 내용이 겉에서 정말 보이지 않는지 tcpdump로 대조합니다. 모두 내 PC의 컨테이너 안에서만 실행합니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11, Docker Desktop, Git Bash에서 실행) |
| 리눅스 커널 | 6.6.87.2-microsoft-standard-WSL2 (WireGuard 인터페이스 생성 가능) |
| wireguard-tools | v1.0.20260223 (alpine 컨테이너에 apk로 설치) |
| 그 밖의 도구 | iproute2, tcpdump, netcat-openbsd (같은 컨테이너에 설치) |
| 파이썬 | 3.12 (wg show 결과를 읽는 데만 사용) |
컨테이너에는 NET_ADMIN 권한만 주었고(--privileged는 쓰지 않음), 전용 네트워크 osk-fd-wgnet에만 연결했습니다. 이 커널에서 인터페이스가 만들어지는지는 ip link add wg0 type wireguard로 먼저 확인했습니다. 다른 환경에서는 커널에 WireGuard가 없을 수 있습니다.
1. 구성
| 이름 | 실제 주소(컨테이너 네트워크) | 터널 주소 |
|---|---|---|
osk-fd-wga (A) |
네트워크가 정한 주소 | 10.8.0.1/24 |
osk-fd-wgb (B) |
네트워크가 정한 주소 | 10.8.0.2/24 |
각 컨테이너는 개인 키를 만들고 공개키를 서로 알려 줍니다. A에는 B의 공개키와 보낼 곳(endpoint)인 B의 실제 주소를, B에는 A의 공개키와 A의 실제 주소를 설정합니다. 포트는 양쪽 모두 UDP 51820입니다. 키는 실행할 때마다 새로 만들고 어디에도 저장하지 않으며, 개인 키를 명령행 인자와 표준 입력으로 넘기는 방식이라 시험 환경에서만 써야 합니다.
2. 세 가지 설정과 같은 점검
점검은 두 가지를 봅니다. wg show wg0 dump의 마지막 핸드셰이크 시각과, A에서 10.8.0.2로 보낸 ping 결과입니다. 둘 다 정상이어야 종료 코드 0입니다.
| 경우 | 설정 | 기대 |
|---|---|---|
| 1. 정상 | 서로의 공개키와 허용 주소가 맞음 | 핸드셰이크 있음, ping 성공 |
| 2. 공개키 오류 | A가 B의 공개키 자리에 엉뚱한 키를 적음 | 핸드셰이크 없음, ping 실패 |
| 3. 허용 주소 오류 | B가 A에게 허용한 주소를 10.9.9.9/32로 잘못 적음 |
핸드셰이크 있음, ping 실패(?) |
3번의 결과가 이 글에서 가장 알아 둘 만한 부분이라 물음표를 붙였습니다. 실제 결과는 다음과 같았습니다.
## 1. 정상 설정
핸드셰이크 2초 전 받음 348B 보냄 404B 허용 주소 10.8.0.2/32
ping 성공
종료 코드 0
## 2. A 가 B 의 공개키를 잘못 적음
핸드셰이크 없음 받음 0B 보냄 148B 허용 주소 10.8.0.2/32
ping 실패
종료 코드 1
## 3. B 가 A 의 주소를 잘못 허용함
핸드셰이크 4초 전 받음 92B 보냄 404B 허용 주소 10.8.0.2/32
ping 실패
종료 코드 1

- 2번은 보내기만 했습니다. A는 148바이트(첫 핸드셰이크 요청)를 보냈지만 받은 것이 0바이트이고 핸드셰이크 시각이 없습니다. 상대가 키가 맞지 않는 요청을 응답 없이 버리는 모습입니다.
- 3번은 핸드셰이크가 되었는데 ping이 실패했습니다. 받은 바이트가 92로 핸드셰이크 응답까지만 왔고 ping 응답은 오지 않았습니다. B가 A의 주소를 허용 목록에 두지 않아 B가 A에게 보내려는 응답이 걸러진 것으로 보이며, B 쪽의 카운터까지는 확인하지 않았습니다.
- 그래서 핸드셰이크만으로 "연결됨"이라고 판단하면 안 됩니다. 키가 맞는지(핸드셰이크)와 주소가 맞는지(허용 주소, 실제 통신)는 별개입니다.
3. 터널 안의 내용은 겉에서 보이는가
정상 설정으로 복구한 뒤, A의 eth0에서 B로 향하는 패킷을 tcpdump로 저장하면서 같은 문자열 SECRETMARKER를 두 가지 길로 보냈습니다.
- 터널 안:
10.8.0.2:9000으로 TCP 전송 - 터널 밖: B의 실제 주소
:9001로 일반 TCP 전송
| 확인 | 결과 |
|---|---|
| 터널로 오간 UDP 51820 패킷 | 10개 |
포트 9000(터널 안)으로 SECRETMARKER가 겉에 보인 횟수 |
0 |
UDP 51820 패킷 안에 SECRETMARKER가 보인 횟수 |
0 |
포트 9001(터널 밖)으로 SECRETMARKER가 겉에 보인 횟수 |
1 |

같은 문자열을 보냈는데 터널 밖의 길에서는 한 번 보이고 터널 안의 길에서는 겉에 나타나지 않았습니다. 이 대조가 있어야 "안 보인다"의 이유가 "캡처가 잘못되어서"가 아니라 "암호화되어서"라고 말할 수 있습니다. 겉에서 보이는 것은 UDP 51820의 길이 148, 92, 96짜리 패킷뿐이었습니다. 앞의 둘은 핸드셰이크의 요청과 응답으로 보이며, 패킷 종류별 해석은 WireGuard 문서와 대조하지 않았습니다.
4. 점검을 종료 코드로
wg_summary.py는 wg show wg0 dump를 표준 입력으로 받아 핸드셰이크가 없거나 --ping 0이면 종료 코드 1로 끝납니다. 첫 줄에는 개인 키가 들어 있어서 읽지 않고 버립니다. 같은 스크립트를 세 경우에 똑같이 적용한 결과가 0, 1, 1이었습니다. 운영에서는 핸드셰이크가 180초 넘게 없으면 문제라고 보는 식으로 시간 기준을 정하는데, 이 글에서는 시간 기준을 따로 시험하지 않았습니다. ping 실패와 핸드셰이크 없음을 다른 알림으로 나누는 것도 해 보지 않았습니다.
전체 코드
전체를 한 번에 돌리는 스크립트입니다. 같은 폴더의 wg_summary.py가 필요합니다.
# wg_demo.sh
#!/usr/bin/env bash
# 컨테이너 두 개 사이에 WireGuard 터널을 만들고, 정상 설정과 틀린 설정 두 가지를 같은 방법으로 점검한다.
# 준비: Docker(Linux 컨테이너, WireGuard 를 지원하는 커널), python, 같은 폴더에 wg_summary.py.
# 주의: 키는 시험용으로 매번 새로 만들며 어디에도 저장하지 않는다.
# 실행(Git Bash): bash wg_demo.sh (약 2분)
export MSYS_NO_PATHCONV=1
NET=osk-fd-wgnet; A=osk-fd-wga; B=osk-fd-wgb
cleanup() { docker rm -f $A $B >/dev/null 2>&1; docker network rm $NET >/dev/null 2>&1; }
cleanup
docker network create $NET >/dev/null
for n in $A $B; do
docker run -d --name $n --network $NET --cap-add NET_ADMIN alpine sh -c \
'apk add -q wireguard-tools iproute2 tcpdump netcat-openbsd >/dev/null 2>&1 && touch /ready && sleep 3600' >/dev/null
done
for n in $A $B; do until docker exec $n test -f /ready 2>/dev/null; do sleep 1; done; done
ip_of() { docker inspect -f '{{(index .NetworkSettings.Networks "'$NET'").IPAddress}}' "$1"; }
IPA=$(ip_of $A); IPB=$(ip_of $B)
KA=$(docker exec $A wg genkey); KB=$(docker exec $B wg genkey); KX=$(docker exec $A wg genkey)
PA=$(echo "$KA" | docker exec -i $A wg pubkey); PB=$(echo "$KB" | docker exec -i $B wg pubkey); PX=$(echo "$KX" | docker exec -i $A wg pubkey)
up() { # up <컨테이너> <개인키> <터널 IP> <상대 공개키> <상대 실제 IP> <상대에게 허용할 주소>
docker exec -i $1 sh -c "cat > /tmp/k; ip link del wg0 2>/dev/null; ip link add wg0 type wireguard && \
wg set wg0 listen-port 51820 private-key /tmp/k peer $4 endpoint $5:51820 allowed-ips $6 && \
ip addr add $3/24 dev wg0 && ip link set wg0 up" <<<"$2"
}
case_run() { # case_run <이름> <A가 믿는 B의 공개키> <A 가 B에 허용한 주소> <B 가 A에 허용한 주소>
echo "## $1"
up $A "$KA" 10.8.0.1 "$2" $IPB "$3"
up $B "$KB" 10.8.0.2 "$PA" $IPA "$4"
if docker exec $A ping -c 2 -W 2 10.8.0.2 >/dev/null 2>&1; then OK=1; else OK=0; fi
docker exec $A wg show wg0 dump | python wg_summary.py --ping $OK; echo " 종료 코드 $?"
}
case_run "1. 정상 설정" "$PB" 10.8.0.2/32 10.8.0.1/32
case_run "2. A 가 B 의 공개키를 잘못 적음" "$PX" 10.8.0.2/32 10.8.0.1/32
case_run "3. B 가 A 의 주소를 잘못 허용함" "$PB" 10.8.0.2/32 10.9.9.9/32
echo "## 4. 겉으로 보이는 패킷에 내용이 있는가(정상 설정으로 복구해 비교)"
up $A "$KA" 10.8.0.1 "$PB" $IPB 10.8.0.2/32
up $B "$KB" 10.8.0.2 "$PA" $IPA 10.8.0.1/32
docker exec -d $B sh -c 'nc -l -p 9000 >/dev/null; true'
docker exec -d $B sh -c 'nc -l -p 9001 >/dev/null; true'
docker exec -d $A sh -c "tcpdump -nn -i eth0 -w /tmp/o.pcap host $IPB >/dev/null 2>&1"
sleep 2
docker exec $A sh -c "echo SECRETMARKER | nc -w 1 10.8.0.2 9000" # 터널 안으로
docker exec $A sh -c "echo SECRETMARKER | nc -w 1 $IPB 9001" # 터널 밖으로(일반 TCP)
sleep 1
docker exec $A pkill tcpdump; sleep 1
echo -n " 터널로 보낸 쪽(UDP 51820) 패킷: "; docker exec $A sh -c "tcpdump -nn -r /tmp/o.pcap udp port 51820 2>/dev/null | wc -l"
echo -n " 터널로 보낸 내용이 겉에 보인 횟수(포트 9000): "; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap tcp port 9000 2>/dev/null | grep -c SECRETMARKER; true"
echo -n " 터널 밖으로 보낸 내용이 겉에 보인 횟수(포트 9001): "; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap tcp port 9001 2>/dev/null | grep -c SECRETMARKER; true"
echo -n " UDP 51820 패킷 안에 SECRETMARKER: "; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap udp port 51820 2>/dev/null | grep -c SECRETMARKER; true"
echo "## 5. 겉에서 본 패킷 모양"
echo " [터널] UDP 51820 (처음 3개)"; docker exec $A sh -c "tcpdump -nn -r /tmp/o.pcap udp port 51820 2>/dev/null | head -3 | cut -d' ' -f1-8,10-"
echo " [터널 밖] TCP 9001 의 내용이 든 줄"; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap tcp port 9001 2>/dev/null | grep SECRETMARKER | cut -c1-60"
cleanup
echo "## 끝"
wg show wg0 dump를 읽어 핸드셰이크와 ping 결과로 종료 코드를 정하는 스크립트입니다.
# wg_summary.py
#!/usr/bin/env python3
"""`wg show wg0 dump` 출력을 표준 입력으로 받아 핸드셰이크와 전송량을 보여 주고,
핸드셰이크가 없거나 ping 이 실패하면 종료 코드 1 로 끝낸다.
사용: wg show wg0 dump | python wg_summary.py --ping 0|1 (개인 키가 든 첫 줄은 읽지 않고 버린다)"""
import sys
import time
sys.stdout.reconfigure(encoding="utf-8")
ping_ok = sys.argv[sys.argv.index("--ping") + 1] == "1" if "--ping" in sys.argv else False
lines = [l for l in sys.stdin.read().splitlines() if l.strip()][1:] # 첫 줄은 인터페이스(개인 키 포함)
if not lines:
print(" 피어 없음")
sys.exit(1)
shake_ok = False
for l in lines:
pub, _psk, endpoint, allowed, shake, rx, tx, _ka = l.split("\t")
age = int(time.time()) - int(shake) if int(shake) else None
shake_ok = shake_ok or age is not None
print(f" 피어 {pub[:8]}… 핸드셰이크 {'없음' if age is None else f'{age}초 전'} 받음 {rx}B 보냄 {tx}B 허용 주소 {allowed}")
print(f" ping {'성공' if ping_ok else '실패'}")
sys.exit(0 if (shake_ok and ping_ok) else 1)
자주 막히는 곳
| 증상 | 원인 | 해결 |
|---|---|---|
ip link add wg0 type wireguard가 실패 |
커널에 WireGuard가 없거나 권한 부족 | --cap-add NET_ADMIN과 커널 지원 확인 |
| 컨테이너가 준비되기 전에 명령이 실패 | apk add가 끝나기 전 |
컨테이너 안에 /ready 파일을 만들고 기다림 |
| 핸드셰이크가 없음 | 상대 공개키 오류, 포트 차단, endpoint 주소 오류 |
공개키와 UDP 51820 도달 여부 확인 |
| 핸드셰이크는 있는데 ping이 실패 | 한쪽의 허용 주소가 상대 터널 주소를 포함하지 않음 | 양쪽 allowed-ips 확인 |
| 파이썬이 한글을 못 씀 | Windows 콘솔 기본 인코딩 | sys.stdout.reconfigure(encoding="utf-8") |
pkill 뒤 파일이 비어 있음 |
tcpdump가 쓰기를 끝내기 전에 읽음 | 종료 신호 뒤 1초 기다림 |
확인 범위
- 해 본 것: 2026-10-30, Windows 11 · Docker 29.5.3 · WSL2 커널 6.6.87.2 · wireguard-tools v1.0.20260223에서 컨테이너 두 개 사이의 터널 생성, 정상 설정(핸드셰이크 있음, ping 성공), 공개키 오류(핸드셰이크 없음), 허용 주소 오류(핸드셰이크 있음, ping 실패), 종료 코드 변환(0, 1, 1), tcpdump로 터널 안과 밖의 문자열 노출 비교(0회 대 1회)를 실행했습니다. 전체 스크립트를 다섯 번 이상 실행했고 1번부터 4번까지의 결과는 매번 같았으며, 끝에 컨테이너와 네트워크를 지웠습니다.
- 해 보지 않은 것: 서로 다른 호스트 사이의 터널, 포트 포워딩과 NAT 통과,
PersistentKeepalive, 사전 공유 키, 여러 피어, 클라이언트 앱, 성능 측정, 핸드셰이크 시간 기준, Linux 호스트와 macOS. - 읽을 때 주의: 5번 단계에서 터널 패킷을 처음 3개 보여 줄 때, 한 줄만 출력된 적이 한 번 있고 원인은 확인하지 않았습니다. 그 뒤 세 번은 세 줄(148, 92, 96)이 나왔습니다. 키는 매번 새로 만든 시험용이며 실제 환경에서는 개인 키를 명령행에 넘기지 않습니다. 출력과 바이트 수는 이 버전과 이 환경의 값입니다.
이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.
이 글의 다음 단계
- GitHub Dependabot 켜기: 취약한 의존성 알림과 자동 수정 PR 받기오래된 버전을 고정한 requirements.txt를 시험 저장소에 넣고 Dependency graph, Dependabot alerts, Dependabot security updates를 켭니다. 알림 47건이 뜨는 것과 Dependabot이 올린 수정 풀 리퀘스트를 확인하고, 하나를 병합해 열린 알림이 36건으로 줄어드는 것까지 봅니다.
- GitHub ruleset으로 main 보호: 직접 푸시와 강제 푸시 막기GitHub 저장소에 ruleset을 만들어 main 브랜치의 삭제, 직접 푸시, 강제 푸시를 막습니다. 규칙을 켠 뒤 직접 푸시와 강제 푸시가 GH013 오류로 거부되는 것을 확인하고, 풀 리퀘스트로는 같은 변경이 들어가는 것까지 시험합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com