설정 파일에는 데이터베이스 비밀번호와 API 토큰이 들어가는 일이 흔합니다. 이 파일을 저장소에 올리면 비밀이 새고, 올리지 않으면 팀원과 서버가 설정을 맞추기 어렵습니다. sops는 YAML, JSON 같은 파일에서 값만 암호화하고 키 이름과 구조는 그대로 두는 오픈소스 도구입니다. 그래서 암호화된 파일을 저장소에 올려도 되고, 코드 리뷰에서는 어느 항목이 바뀌었는지 볼 수 있습니다. age는 sops가 데이터 키를 감싸는 데 쓰는 작고 단순한 암호화 도구입니다. 이 글은 두 도구를 일회용 컨테이너에서 실행해 암호화부터 키 추가까지 해 보고, 무엇이 지켜지고 무엇이 지켜지지 않는지 확인합니다.
비밀값을 중앙에서 저장하고 정책으로 읽기 권한을 나누는 방법은 Vault 개발 서버: KV 버전, 읽기 전용 정책 글에서 다룹니다.
준비물
| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11) |
| 도구 | age v1.3.2, sops 3.12.2 (alpine 컨테이너에 apk add age sops로 설치) |
모든 작업은 일회용 컨테이너 안에서 하므로 내 PC에는 아무것도 설치되지 않고 파일도 남지 않습니다. 실제로 쓸 때는 두 도구를 PC나 CI 서버에 설치합니다.
1. 동작 원리
| 단계 | 일어나는 일 |
|---|---|
| 암호화 | sops가 무작위 데이터 키를 하나 만들어 값들을 암호화. 그 데이터 키를 받는 사람의 age 공개 키로 감싸 파일 끝(sops: 블록)에 저장 |
| 복호화 | 받는 사람이 자기 age 비밀 키로 데이터 키를 풀고, 그 키로 값을 복호화 |
| 무결성 | 파일 전체의 서명(MAC)을 함께 저장해, 암호화되지 않은 줄의 변경도 감지 |
공개 키는 받는 사람의 "주소"이고 공유해도 안전합니다. 비밀 키 파일(key.txt)이 진짜 열쇠이므로 저장소에 올리지 않고 각자 보관합니다.
2. 키와 평문 설정 파일
age-keygen -o key.txt로 키 한 쌍을 만들면 공개 키(age1...로 시작)가 출력되고 비밀 키는 파일에 저장됩니다. 실습용 설정 파일은 이렇습니다.
app:
name: payroll
debug: false
db:
host: db.internal
user: app
password: S3cr3t-DB-Pass
api:
token: tok_live_ABC123XYZ
비밀은 password와 token 두 값뿐이고 나머지는 숨길 필요가 없는 평범한 설정입니다.
3. 규칙 파일(.sops.yaml)과 암호화
어떤 값을 어떤 키로 암호화할지는 .sops.yaml에 적습니다.
creation_rules:
- path_regex: secrets(\.enc)?\.yaml$
encrypted_regex: '^(password|token)$'
age: age1...(공개 키)
| 항목 | 뜻 |
|---|---|
path_regex |
이 규칙을 적용할 파일 이름. 이 글에서는 secrets.yaml과 secrets.enc.yaml |
encrypted_regex |
키 이름이 이 식에 맞는 값만 암호화. 여기서는 password와 token |
age |
받는 사람의 공개 키. 쉼표로 여러 개 적을 수 있음 |
sops -e secrets.yaml > secrets.enc.yaml로 암호화했습니다. 결과 파일은 이런 모양입니다(값은 앞부분만 줄였습니다).
app:
name: payroll
debug: false
db:
host: db.internal
user: app
password: ENC[...4nkFb2...]
api:
token: ENC[...lax0Wn...]
sops:
age:
- recipient: age1...
enc: (age가 감싼 데이터 키)
lastmodified: "2026-10-29T08:54:15Z"
mac: ENC[...]
encrypted_regex: ^(password|token)$
version: 3.12.2
name,host,user같은 일반 설정은 그대로 읽힙니다. 무엇이 어디에 설정되어 있는지 알아볼 수 있습니다.password와token만ENC[AES256_GCM,...]으로 바뀌었습니다. 암호화된 파일에서 평문 비밀 문자열을 찾으니 두 값 모두 0건이었습니다.- 아래쪽
sops:블록에는 받는 사람, 감싼 데이터 키, 수정 시각, 파일 서명(mac)이 들어 있습니다.
일부만 암호화하는 방식의 장점은 코드 리뷰에서 드러납니다. 누가 db.host를 바꾸면 변경이 그대로 보이고, 비밀 값이 바뀌면 암호문이 바뀐 것만 보입니다. 모든 값을 암호화하는 기본 설정(encrypted_regex를 쓰지 않음)도 가능한데, 그러면 어떤 항목이 있는지도 알 수 없어서 리뷰가 어렵습니다. 이 글의 host와 user는 숨기지 않기로 정한 값입니다. 숨겨야 하는 정보(내부 주소, 사용자 이름 등)가 있다면 그 키 이름도 규칙에 넣습니다.

4. 복호화
비밀 키 파일의 위치를 환경 변수 SOPS_AGE_KEY_FILE로 알려 주고 sops -d를 실행하면 원래 값이 나옵니다.
| 명령 | 결과 |
|---|---|
sops -d secrets.enc.yaml |
전체를 복호화. password: S3cr3t-DB-Pass, token: tok_live_ABC123XYZ |
sops -d --extract '["db"]["password"]' secrets.enc.yaml |
값 하나만 출력: S3cr3t-DB-Pass |
--extract는 배포 스크립트에서 비밀 하나만 환경 변수나 다른 프로그램의 입력으로 넘길 때 씁니다. 복호화한 평문을 파일로 저장하면 비밀이 디스크에 남으므로, 가능하면 파이프로 바로 넘기고 파일로 만들지 않습니다.
5. 키가 없거나 틀리면
| 상황 | 결과 |
|---|---|
| 비밀 키 지정 없음 | Failed to get the data key required to decrypt the SOPS file. |
| 다른 사람의 비밀 키 | 같은 오류. 자세한 설명에 identity did not match any of the recipients(키가 받는 사람과 맞지 않음)가 들어 있음 |
받는 사람 목록에 없는 키로는 열 수 없습니다. 비밀 키를 잃으면 이 파일의 비밀을 복구할 방법이 없으므로, 받는 사람을 둘 이상으로 하고 비밀 키는 안전한 곳에 따로 보관합니다.
6. 변조 감지
암호화되지 않은 줄과 암호화된 값을 각각 바꿔 보았습니다.
| 변조 | 결과 |
|---|---|
평문 줄 host: db.internal을 host: evil.example로 바꿈 |
MAC mismatch. 복호화 거부 |
암호화된 token 값의 암호문 일부를 바꿈 |
Could not decrypt with AES_GCM: cipher: message authentication failed |
두 번째는 예상된 결과입니다. 중요한 것은 첫 번째입니다. 암호화하지 않은 줄을 바꿨는데도 복호화가 거부되었습니다. 파일 서명(MAC)이 암호화하지 않은 값까지 포함하기 때문입니다. 누군가 host를 공격자의 서버로 몰래 바꿔 저장소에 올려도, 비밀을 풀기 전에 알아챌 수 있습니다. 평문으로 둔 값도 변조에서 보호된다는 뜻입니다.
7. 값 수정과 바뀌는 줄
sops set secrets.enc.yaml '["db"]["password"]' '"N3w-DB-Pass"'로 비밀번호 하나를 바꿨습니다. 파일에서 바뀐 줄은 이렇습니다.
- password: ENC[AES256_GCM,data:4nkFb...
+ password: ENC[AES256_GCM,data:ZMB/4...
- lastmodified: "2026-10-29T08:54:15Z
- mac: ENC[AES256_GCM,data:G7ifEBuMtZ...
+ lastmodified: "2026-10-29T08:54:16Z
+ mac: ENC[AES256_GCM,data:GlUngR9//y...
바뀐 것은 password 한 줄과 수정 시각, 서명 줄뿐이었습니다. token과 일반 설정은 그대로입니다. 그래서 저장소의 변경 내용이 작고, 다른 항목을 건드렸는지 리뷰에서 확인할 수 있습니다.
8. 받는 사람 추가
팀원이 늘면 받는 사람(공개 키)을 추가하고 sops updatekeys로 파일을 다시 맞춥니다. .sops.yaml의 age: 값에 쉼표로 새 공개 키를 덧붙이고 실행했습니다.
| 확인 | 결과 |
|---|---|
updatekeys 실행 |
File ... synced with new keys |
| 파일 안의 받는 사람 수 | 2 |
새 키(팀원)로 token 복호화 |
tok_live_ABC123XYZ |
값 자체는 다시 암호화되지 않고 데이터 키를 감싸는 부분만 갱신되는 것으로 추정합니다. 이 글에서 암호문이 바뀌었는지는 비교하지 않았습니다. 팀원이 나갈 때는 받는 사람에서 빼고 updatekeys를 하면 되지만, 그 사람이 이미 복호화해 본 비밀은 알고 있으므로 비밀 값 자체를 바꿔야 합니다. 이 점은 sops의 한계가 아니라 비밀 관리 전반의 원칙입니다.

9. 쓸 때 정할 것
| 항목 | 내용 |
|---|---|
| 비밀 키 보관 | 개인별로 따로 두고 저장소에 올리지 않음. 비밀번호 관리자나 하드웨어 키에 보관 |
| 받는 사람 | 사람과 서버(배포용 키)를 구분. 둘 이상으로 두어 한 사람이 키를 잃어도 열 수 있게 함 |
| 어떤 값을 암호화하나 | encrypted_regex에 비밀이 되는 키 이름을 빠짐없이 기재. 새 비밀 항목을 추가하면 규칙도 맞는지 확인 |
| 평문 노출 | 복호화한 값을 파일, 로그, 명령 기록에 남기지 않기 |
| 배포 | CI나 서버에는 복호화용 비밀 키를 환경 변수나 비밀 저장소로 주입. 이 글에서는 시험하지 않음 |
| 이력 | 이미 평문으로 저장소에 올라간 비밀은 지워도 이력에 남음. 그 비밀은 이미 새어 나갔다고 보고 값을 교체 |
전체 코드
위 1~8절을 한 번에 실행하는 파일입니다. sops_demo.sh로 저장하고 bash sops_demo.sh로 실행합니다. 일회용 alpine 컨테이너 안에서 age와 sops를 설치해 쓰므로 내 PC에는 아무것도 남지 않습니다. 이 PC에서는 약 1분이 걸렸습니다. 키, 비밀번호, 토큰은 모두 실습용입니다.
#!/usr/bin/env bash
# sops 와 age 로 설정 파일의 비밀 값만 암호화하고, 복호화, 키 없음/틀린 키, 변조 감지, 값 수정, 받는 사람 추가까지 확인한다.
# 준비: Docker. 모든 작업은 일회용 alpine 컨테이너 안에서 하고(age, sops 를 설치), 파일은 컨테이너와 함께 사라진다.
# 주의: 이 파일의 키와 비밀 값은 모두 실습용이다. 실제 비밀을 넣지 않는다.
# 실행(Git Bash): bash sops_demo.sh (약 1분)
export MSYS_NO_PATHCONV=1
docker run --rm -i alpine sh -s <<'INNER'
apk add --no-cache age sops >/dev/null 2>&1
export SOPS_DISABLE_VERSION_CHECK=1 2>/dev/null
cd /tmp && mkdir w && cd w
echo "## 1. 도구 버전과 키 만들기"
echo "age $(age --version), $(sops --version 2>&1 | head -1)"
age-keygen -o key.txt 2>&1 | sed 's/^Public key: /공개 키(받는 사람 주소): /'
PUB=$(grep -o 'age1[a-z0-9]*' key.txt | head -1)
echo "## 2. 평문 설정 파일(secrets.yaml)"
cat > secrets.yaml <<Y
app:
name: payroll
debug: false
db:
host: db.internal
user: app
password: S3cr3t-DB-Pass
api:
token: tok_live_ABC123XYZ
Y
cat secrets.yaml
echo "## 3. .sops.yaml 규칙: password 와 token 값만 암호화"
cat > .sops.yaml <<Y
creation_rules:
- path_regex: secrets(\.enc)?\.yaml\$
encrypted_regex: '^(password|token)\$'
age: $PUB
Y
cat .sops.yaml | sed "s/age1[a-z0-9]*/age1.../"
sops -e secrets.yaml > secrets.enc.yaml
echo "-- 암호화된 파일(secrets.enc.yaml)"
sed 's/ENC\[AES256_GCM,data:\([^,]\{6\}\)[^]]*\]/ENC[...\1...]/; s/age1[a-z0-9]*/age1.../; s/mac: .*/mac: ENC[...]/; s/enc: .*/enc: (age 가 감싼 데이터 키)/' secrets.enc.yaml | grep -v -E '^\s+(-----|[A-Za-z0-9+/=]{20,}$)'
echo "평문 비밀이 파일에 남았나: password=$(grep -c 'S3cr3t' secrets.enc.yaml) token=$(grep -c 'ABC123' secrets.enc.yaml) (0 이면 남지 않음)"
echo "## 4. 복호화"
SOPS_AGE_KEY_FILE=key.txt sops -d secrets.enc.yaml | grep -E 'password|token'
echo "-- 값 하나만 꺼내기(--extract)"
SOPS_AGE_KEY_FILE=key.txt sops -d --extract '["db"]["password"]' secrets.enc.yaml; echo
echo "## 5. 키가 없거나 틀리면"
echo "-- 키 없음"
sops -d secrets.enc.yaml 2>&1 | head -2 | cut -c1-110
age-keygen -o other.txt >/dev/null 2>&1
echo "-- 다른 사람의 키"
SOPS_AGE_KEY_FILE=other.txt sops -d secrets.enc.yaml 2>&1 | grep -m2 -E 'Failed|did not match' | cut -c1-110
echo "## 6. 변조 감지: 암호화되지 않은 줄(host)과 암호화된 값(token)을 각각 바꿔 본다"
sed 's/host: db.internal/host: evil.example/' secrets.enc.yaml > t1.yaml
SOPS_AGE_KEY_FILE=key.txt sops -d t1.yaml 2>&1 | head -1 | cut -c1-110
awk '/token: ENC/ { sub(/data:./, "data:Z"); } { print }' secrets.enc.yaml > t2.yaml
SOPS_AGE_KEY_FILE=key.txt sops -d t2.yaml 2>&1 | head -1 | cut -c1-110
echo "## 7. 값 수정(sops set)과 변경된 줄 수"
cp secrets.enc.yaml before.yaml
SOPS_AGE_KEY_FILE=key.txt sops set secrets.enc.yaml '["db"]["password"]' '"N3w-DB-Pass"'
echo "-- 바뀐 줄(diff -u 의 - 와 + 줄, 앞 40글자만)"
diff -u before.yaml secrets.enc.yaml | grep '^[-+] ' | cut -c1-40
SOPS_AGE_KEY_FILE=key.txt sops -d --extract '["db"]["password"]' secrets.enc.yaml; echo
echo "## 8. 받는 사람 추가(updatekeys): 팀원의 키로도 열 수 있게"
PUB2=$(grep -o 'age1[a-z0-9]*' other.txt | head -1)
sed "s/age: \(age1[a-z0-9]*\)/age: \1,$PUB2/" .sops.yaml > .sops.yaml.new && mv .sops.yaml.new .sops.yaml
SOPS_AGE_KEY_FILE=key.txt sops updatekeys -y secrets.enc.yaml 2>&1 | tail -1
echo "받는 사람 수: $(grep -c 'recipient: age1' secrets.enc.yaml)"
echo "-- 새 키(other.txt)로 복호화"
SOPS_AGE_KEY_FILE=other.txt sops -d --extract '["api"]["token"]' secrets.enc.yaml; echo
INNER
자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
no matching creation rules found |
.sops.yaml의 path_regex가 파일 이름과 맞지 않음. 처음에 secrets\.yaml$만 적었더니 secrets.enc.yaml에는 규칙이 없어 이 오류가 났고, (\.enc)?를 넣어 해결 |
Failed to get the data key |
비밀 키를 못 찾았거나 받는 사람이 아님. SOPS_AGE_KEY_FILE 경로와 공개 키 확인 |
MAC mismatch |
파일의 평문 줄이나 암호문을 누군가 바꿈. 의도한 수정이라면 sops set이나 sops 파일로 수정. 편집기로 직접 고치면 서명이 맞지 않음 |
| 평문이 파일에 남아 있음 | encrypted_regex에 그 키 이름이 없음. 규칙을 고치고 평문 파일에서 다시 암호화 |
| 새 버전 안내 메시지 출력 | 도구가 새 버전을 알리는 정보 메시지. 동작에는 영향 없음 |
확인 범위
- 해 본 것: 2026-10-29, Windows 11 · Docker 29.5.3 · age v1.3.2 · sops 3.12.2(일회용 컨테이너)에서 키 생성, 일부 값 암호화, 복호화와 값 하나 꺼내기, 키 없음과 틀린 키, 평문 줄과 암호문 변조,
sops set, 받는 사람 추가(updatekeys)를 실행했습니다. 같은 스크립트를 여러 번 실행했고 결과가 같았습니다. - 해 보지 않은 것: 클라우드 키 관리 서비스(AWS KMS 등)와의 연동, git 훅과 CI 연동,
sops 파일로 편집기 열기, JSON과 .env 형식, 받는 사람 제거, 키 교체(rotation) 절차, 큰 파일의 속도, Linux 서버 설치, Windows 설치 버전. - 읽을 때 주의: 이 글의 비밀과 키는 실습용으로 만든 값입니다. 평문 줄을 바꿔도 복호화가 거부되는 동작은 이 버전(3.12.2)에서 본 결과입니다.
이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.
이 글의 다음 단계
- npm audit --audit-level 사용법: 종료 코드로 배포 막기npm audit --audit-level은 지정한 심각도 이상의 취약점이 있을 때만 종료 코드 1을 돌려줍니다. low부터 critical까지 단계별 종료 코드와 --omit=dev를 붙였을 때의 차이를 실제 실행 결과로 확인합니다. npm script와 CI 단계에 넣는 방법도 정리합니다.
- package.json과 package-lock.json 차이: npm ci로 확인하기package.json에는 허용하는 버전 범위가, package-lock.json에는 실제로 설치된 버전과 integrity 해시가 적힙니다. 같은 프로젝트에서 npm install과 npm ci를 번갈아 실행해 두 파일의 역할과 두 명령의 차이를 실제 출력으로 확인합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com