비밀번호와 API 키를 코드나 환경 변수에 두지 않으려면 비밀값을 따로 보관하고, 누가 무엇을 읽었는지 남기고, 접근을 짧게 허용하는 서버가 필요합니다. HashiCorp Vault가 그 일을 하는 대표적인 도구입니다. 앞의 sops와 age 글이 파일에 담긴 비밀을 암호화해 저장소에 두는 방법이었다면, 이 글은 실행 중인 서버에서 비밀을 꺼내 쓰는 방법입니다. 개발 서버(dev mode)를 내 PC의 컨테이너로 띄워서 저장, 버전, 정책, 만료, 감사 로그를 직접 실행해 보고 그 결과를 기록합니다. 개발 서버는 시험용이라 운영에 쓰지 않습니다. 이유도 7번에서 직접 확인합니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11, Git Bash에서 실행) |
| Vault | 2.2.1 (hashicorp/vault 이미지) |
| 실행 방식 | 개발 서버: 메모리 저장(inmem), 자동으로 잠금 해제, root 토큰 고정(root-lab-token) |
| 파이썬 | 3.12 (토큰 정보와 감사 로그를 읽는 데만 사용) |
모든 명령은 docker exec로 컨테이너 안의 vault 명령을 실행합니다. 서버 주소는 http://127.0.0.1:8200이고, 포트는 바깥에 열지 않았습니다.
1. 개발 서버 띄우기
docker run -d --name osk-vault --cap-add IPC_LOCK \
-e VAULT_DEV_ROOT_TOKEN_ID=root-lab-token \
-e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \
hashicorp/vault:latest
vault status로 상태를 보면 Initialized true, Sealed false, Storage Type inmem이 나옵니다. 운영 서버는 처음에 초기화하고 열쇠 조각(unseal key)으로 잠금을 풀어야 하는데, 개발 서버는 이 과정을 자동으로 해 주고 데이터를 메모리에만 둡니다. 편하지만 시험용으로만 씁니다.
2. KV v2: 저장, 덮어쓰기, 옛 버전, 삭제와 복구
KV 버전 2 저장소는 같은 경로에 쓸 때마다 버전이 올라갑니다.
vault kv put -mount=secret app/db user=app pass=first
vault kv put -mount=secret app/db user=app pass=second # version 2
vault kv get -mount=secret -field=pass app/db # second
vault kv get -mount=secret -version=1 -field=pass app/db # first
두 번째 put의 결과에 version 2가 나왔고, 현재 값은 second, 1번 버전은 first였습니다. 값을 덮어써도 옛 값이 남으므로 실수로 바꾼 값을 되돌릴 수 있습니다. 반대로 이미 유출된 옛 값도 남아 있다는 뜻이므로 비밀을 바꿀 때는 옛 버전을 destroy해야 합니다(destroy는 이 글에서 시험하지 않았습니다).
vault kv delete는 값을 지우는 것이 아니라 삭제 표시를 합니다. 삭제한 뒤에 kv get을 하면 값 줄이 0개였고 deletion_time만 표시되었습니다. vault kv undelete -versions=2를 하자 값 second가 돌아왔습니다.
3. 읽기 전용 정책과 20초짜리 토큰
Vault는 정책(policy) 파일로 접근을 제어합니다. KV v2에서는 값이 secret/data/... 아래에 있고 이름 목록과 메타데이터가 secret/metadata/... 아래에 있으므로 두 경로를 따로 적어야 합니다. 이 글의 app-read.hcl은 app/ 아래만 읽도록 허용합니다.
path "secret/data/app/*" {
capabilities = ["read"]
}
path "secret/metadata/app/*" {
capabilities = ["list", "read"]
}
정책을 등록하고(vault policy write app-read), 이 정책만 가진 토큰을 20초 수명으로 만들었습니다(vault token create -policy=app-read -ttl=20s). 이 토큰으로 세 가지를 시도했습니다.
| 시도 | 결과 |
|---|---|
secret/app/db 읽기 |
second (성공) |
secret/app/db에 쓰기 |
permission denied |
secret/other/key 읽기(정책 밖 경로) |
permission denied |
토큰은 자신에게 붙은 정책이 허용한 일만 할 수 있습니다. 앱에는 이렇게 읽기만 되는 토큰을 주고, 쓰기는 관리자 도구만 하게 나눕니다. vault token lookup으로 본 남은 수명은 18초였습니다.
처음에 정책 파일을 컨테이너에 넣지 못하고(docker cp가 Git Bash의 경로를 알아듣지 못했습니다) 정책 없이 토큰을 만들었을 때는 읽기부터 403이 났습니다. vault kv get이 값을 읽기 전에 저장소 정보(sys/internal/ui/mounts/secret)를 먼저 물어보는데, 정책이 없으면 이 질문부터 거절되기 때문입니다. 정책이 붙자 바로 해결되었습니다. 이 글의 스크립트는 파일을 표준 입력으로 넘기는 방식으로 바꿨습니다.
4. 토큰이 만료되면
20초가 지난 뒤 같은 토큰으로 읽기를 시도하면 이런 메시지가 나옵니다.
permission denied
"토큰이 만료되었다"는 별도의 문구가 아니라 permission denied였습니다. 정책이 막은 것인지 수명이 끝난 것인지 오류 문구만으로는 구분되지 않으므로, 앱이 갑자기 permission denied를 받으면 토큰의 수명(vault token lookup)도 함께 확인합니다. 수명이 짧은 토큰은 유출되어도 피해가 20초에 그치고, 앱은 주기적으로 새 토큰을 받아야 합니다. 이 글에서는 토큰 갱신(renew)은 시험하지 않았습니다.
5. 감사 로그
감사 로그는 켜야 남습니다(vault audit enable file file_path=/tmp/audit.log). 켠 뒤에 root로 읽기를 한 번, 읽기 전용 토큰으로 쓰기를 한 번 시도한 결과를 로그에서 읽었습니다.
request read secret/data/app/db policies=['root']
request update secret/data/app/db policies=['app-read', 'default']
누가(어떤 정책을 가진 토큰이), 어느 경로에, 어떤 동작을 시도했는지가 남습니다. 두 번째 줄이 거절된 쓰기 시도입니다. 정책 밖의 일을 시도한 토큰이 있는지를 로그에서 찾을 수 있습니다. 로그 파일에서 평문 값 second와 hacked를 찾아보니 0건이었습니다. Vault는 값을 해시로 바꿔 기록하므로 로그가 유출되어도 비밀 값은 읽히지 않습니다. 이 글에서는 해시의 형식이나 비교 방법은 확인하지 않았습니다.

6. HTTP API로 읽기
CLI는 HTTP API를 감싼 것입니다. 앱은 보통 HTTP로 직접 읽습니다. 컨테이너 안의 wget으로 헤더에 토큰을 넣어 읽었습니다.
wget -qO- --header="X-Vault-Token: root-lab-token" http://127.0.0.1:8200/v1/secret/data/app/db
응답에서 version 2, pass second를 읽었습니다. 앱 코드는 이 주소와 X-Vault-Token 헤더만 알면 됩니다. 이 글에서는 앱 쪽 코드 라이브러리는 쓰지 않았습니다.
7. 개발 서버를 재시작하면
컨테이너를 재시작한 뒤 같은 값을 읽자 이런 응답이 나왔습니다.
No value found at secret/data/app/db
개발 서버는 데이터를 메모리에만 두므로 재시작하면 모든 것이 사라집니다. 정책, 토큰, 감사 설정도 같이 사라집니다. 개발 서버를 운영에 쓰면 안 되는 가장 직접적인 이유입니다. 운영에서는 파일이나 통합 저장소(Raft)를 쓰고 열쇠 조각으로 잠금을 풉니다. 이 글에서는 운영 구성을 시험하지 않았습니다.

8. 앱에 연결하는 순서
실제 서비스에서는 보통 이 순서로 씁니다.
- 비밀을
secret/app/...에 넣습니다(관리자 도구). app-read같은 읽기 전용 정책을 만듭니다.- 앱마다 그 정책의 토큰(또는 AppRole 같은 인증 방식)을 짧은 수명으로 발급합니다.
- 앱은 시작할 때 HTTP로 값을 읽습니다.
- 감사 로그를 켜 두고
permission denied가 반복되는 토큰을 살핍니다.
3번의 AppRole 같은 인증 방식은 이 글에서 시험하지 않았습니다. 앞의 Dockle 글에서 본 것처럼 비밀을 이미지의 ENV에 넣지 않고 실행 시점에 이런 서버에서 받아 오는 것이 올바른 방향입니다.
전체 코드
아래 두 파일을 같은 폴더에 두고 bash vault_demo.sh를 실행하면 이 글의 출력을 다시 볼 수 있습니다. 이 PC에서 약 1분이 걸렸고(토큰 만료를 기다리는 22초 포함), 끝에 컨테이너를 지웁니다.
app-read.hcl
# app-read.hcl
# secret/app/ 아래는 읽기와 목록만 허용한다(KV v2 는 data/ 와 metadata/ 경로를 쓴다)
path "secret/data/app/*" {
capabilities = ["read"]
}
path "secret/metadata/app/*" {
capabilities = ["list", "read"]
}
vault_demo.sh
# vault_demo.sh
#!/usr/bin/env bash
# HashiCorp Vault 개발 서버로 KV 저장, 버전, 읽기 전용 정책, 토큰 만료, 감사 로그를 확인한다.
# 준비: Docker, 같은 폴더에 app-read.hcl. 개발 서버는 메모리에만 저장하고 root 토큰이 고정이므로 내 PC 시험 전용이다.
# 실행(Git Bash): bash vault_demo.sh (약 1분)
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
ROOT=root-lab-token
V() { docker exec -e VAULT_ADDR=http://127.0.0.1:8200 -e VAULT_TOKEN="$ROOT" osk-vault vault "$@"; }
VT() { local t="$1"; shift; docker exec -e VAULT_ADDR=http://127.0.0.1:8200 -e VAULT_TOKEN="$t" osk-vault vault "$@"; }
start() {
docker rm -f osk-vault >/dev/null 2>&1
docker run -d --name osk-vault --cap-add IPC_LOCK -e VAULT_DEV_ROOT_TOKEN_ID=$ROOT \
-e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 hashicorp/vault:latest >/dev/null
sleep 4
}
start
echo "## 1. 개발 서버 상태(메모리 저장, 자동 unseal)"
V version | cut -c1-14
V status | grep -E 'Initialized|Sealed|Storage|Version'
echo "## 2. KV v2: 저장, 덮어쓰기(버전 증가), 옛 버전 읽기"
V kv put -mount=secret app/db user=app pass=first >/dev/null
V kv put -mount=secret app/db user=app pass=second | grep -E '^version'
echo -n " 현재 값: "; V kv get -mount=secret -field=pass app/db; echo
echo -n " 1번 버전: "; V kv get -mount=secret -version=1 -field=pass app/db; echo
V kv delete -mount=secret app/db >/dev/null
echo -n " 삭제 뒤: 값 줄 수 "; V kv get -mount=secret app/db 2>&1 | grep -c '^pass'; V kv get -mount=secret app/db 2>&1 | grep deletion_time | sed 's/^/ /'
V kv undelete -versions=2 -mount=secret app/db >/dev/null
echo -n " 복구 뒤: "; V kv get -mount=secret -field=pass app/db; echo
echo "## 3. 읽기 전용 정책과 짧은 수명의 토큰(20초)"
docker exec -i osk-vault sh -c 'cat > /tmp/app-read.hcl' < "$HERE/app-read.hcl" # docker cp 는 Git Bash 경로에서 실패해서 표준 입력으로 넘긴다
V policy write app-read /tmp/app-read.hcl
V kv put -mount=secret other/key value=hidden >/dev/null
TOK=$(V token create -policy=app-read -ttl=20s -field=token)
echo " 토큰 앞 8자: ${TOK:0:8}..."
echo -n " 읽기 secret/app/db : "; VT "$TOK" kv get -mount=secret -field=pass app/db; echo
echo -n " 쓰기 secret/app/db : "; VT "$TOK" kv put -mount=secret app/db pass=hacked 2>&1 | grep -o 'permission denied' | head -1
echo -n " 읽기 secret/other : "; VT "$TOK" kv get -mount=secret other/key 2>&1 | grep -o 'permission denied' | head -1
echo -n " 토큰 남은 수명(초) : "; VT "$TOK" token lookup -format=json | python -c "import json,sys; print(json.load(sys.stdin)['data']['ttl'])"
echo "## 4. 20초가 지난 뒤에 같은 토큰으로 읽기"
sleep 22
echo -n " 읽기: "; VT "$TOK" kv get -mount=secret -field=pass app/db 2>&1 | grep -oE 'permission denied|bad token|invalid token' | head -1
echo "## 5. 감사 로그: 켠 뒤의 요청만 남고, 값은 해시로 가려진다"
V audit enable file file_path=/tmp/audit.log >/dev/null
V kv get -mount=secret -field=pass app/db >/dev/null
TOK2=$(V token create -policy=app-read -ttl=60s -field=token)
VT "$TOK2" kv put -mount=secret app/db pass=hacked >/dev/null 2>&1
docker exec osk-vault cat /tmp/audit.log | python -c "
import json, sys
for line in sys.stdin:
d = json.loads(line)
r = d.get('request', {})
if d['type'] == 'request' and r.get('path', '').startswith('secret/data/app'):
print(f\" {d['type']:8} {r['operation']:7} {r['path']:20} policies={d.get('auth', {}).get('policies')}\")
"
echo -n " 로그에 평문 'second' 가 있는가: "; docker exec osk-vault grep -c second /tmp/audit.log
echo -n " 로그에 평문 'hacked' 가 있는가: "; docker exec osk-vault grep -c hacked /tmp/audit.log
echo "## 6. HTTP API 로도 같은 값을 읽는다(wget)"
docker exec osk-vault wget -qO- --header="X-Vault-Token: $ROOT" http://127.0.0.1:8200/v1/secret/data/app/db \
| python -c "import json,sys; d=json.load(sys.stdin)['data']; print(' version', d['metadata']['version'], 'pass', d['data']['pass'])"
echo "## 7. 개발 서버를 다시 시작하면 데이터가 사라진다"
docker restart osk-vault >/dev/null; sleep 4
echo -n " 재시작 뒤 읽기: "; V kv get -mount=secret app/db 2>&1 | head -1 | cut -c1-70
echo "## 8. 정리"
docker rm -f osk-vault >/dev/null
docker ps -a --format '{{.Names}}' | grep -c osk-vault
자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
docker cp가 The system cannot find the file specified로 실패합니다 |
Git Bash의 경로를 Windows의 Docker가 알아듣지 못합니다. docker exec -i ... sh -c 'cat > 파일' < 파일로 표준 입력으로 넘깁니다 |
토큰으로 kv get을 하면 preflight capability check returned 403이 나옵니다 |
토큰에 정책이 없거나 경로가 정책에 없습니다. KV v2는 secret/data/...와 secret/metadata/...를 따로 허용합니다 |
토큰이 만료되었는데 permission denied만 나옵니다 |
만료와 정책 거절이 같은 문구입니다. vault token lookup으로 수명을 확인합니다 |
| 감사 로그에 값이 보이지 않습니다 | 의도된 동작입니다. 값은 해시로 기록됩니다 |
| 재시작하니 모두 사라졌습니다 | 개발 서버는 메모리 저장입니다. 시험 데이터는 스크립트로 다시 만들 수 있게 둡니다 |
확인 범위
- 해 본 것: 2026-10-30, Windows 11 · Docker 29.5.3 · Vault 2.2.1 개발 서버에서 KV v2 저장과 버전, 삭제와 복구, 읽기 전용 정책과 20초 토큰(읽기 성공, 쓰기와 정책 밖 읽기 거절), 만료 뒤의 거절, 감사 로그(평문 값 0건), HTTP API 읽기, 재시작 뒤 데이터 손실을 실행했습니다. 전체 스크립트를 세 번 실행해 결과가 같았고, 끝에 컨테이너와 네트워크를 지웠습니다.
- 해 보지 않은 것: 운영 구성(초기화, unseal key, Raft), 토큰 갱신과 AppRole, 데이터베이스 동적 비밀, 암호화 엔진(transit),
destroy와 버전 보존 설정, 감사 로그의 해시 비교, 앱 코드 라이브러리 연동, Linux와 macOS. - 읽을 때 주의: 이 글의 root 토큰(
root-lab-token)은 시험용으로 고정한 값이며 실제 환경에서는 쓰지 않습니다. 개발 서버는 TLS 없이 HTTP로 열려 있으므로 같은 네트워크의 다른 장치가 접근할 수 있는 곳에서는 실행하지 않습니다. 오류 문구와 명령 출력은 이 버전(2.2.1)의 것입니다.
이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.
이 글의 다음 단계
- 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